ice icon indicating copy to clipboard operation
ice copied to clipboard

Ending '@see' Attributes with Periods

Open InsertCreativityHere opened this issue 5 years ago • 0 comments

Currently, when we use @see attributes in Slice doc comments, we don't end them in periods. For example:

/// The remote invocation metrics map.
/// @see RemoteMetrics
MetricsMap remotes;

The code we generate for Java and C# just copy the @see ... directly. This is fine for Java, but causes StyleCop warnings in C# (where it wants these lines to end in a period).

Changing the Slice comments to end in a period fixes the C# warnings, but breaks the JavaDoc generation. When JavaDoc sees a period in an @see attribute, it expects a package name, and hence for there to be a name after the period.

Should we leave the Slice files as is, and make the C# compiler auto-generate a terminating period? Or should we add a period to the Slice comments, and make the Java compiler cut out these trailing periods?

InsertCreativityHere avatar Oct 07 '20 15:10 InsertCreativityHere