3

What is the most appropriate way of writing this comment:

    /// <summary>
    /// Order - Identifies the ordinal location of this category
    ///     relative to other listed categories.
    /// </summary>

if I'm wanting to wrap "category" in <see> tags? I've considered:

    /// <summary>
    /// Order - Identifies the ordinal location of this <see cref="Category"/>
    ///     relative to other listed <see cref="Category"/>'s.
    /// </summary>

Do you see my dilemma?

Edit:

I should add that I am using Visual Studio's XML Comments. So I am somewhat restricted as to the schema. I believe cref has to point to a valid type reference.

3 Answers 3

5

The best way to do this is actually to specify another piece of text separate from the link.

for your example instead of writing

<see cref="Category"/>

write

<see cref="Category">Categories</see>.

The lack of a / at the end of the statement means that the next segment will become the actual string of the link, so you'll get a link from the word "Categories" that will actually refer to the "Category" object. This can also be useful to fit links more naturally into your documentation in other ways, such as breaking up a two-word type name into two actual words separated by a space, or shortening a long type name.

2
  • That is exactly what I was looking for. :)
    – Jordan
    Jun 21, 2011 at 13:23
  • 1
    This doesn't seem to work anymore, at least not in VS2017. With A list of <see cref="Category">Categories</see> is cool in my XML doc, I still get A list of Category is cool. in intellisense. May 23, 2017 at 11:12
4

Don't try to pluralize a tag; it's hard to read. Use something like this:

/// <summary>
/// Order - Identifies the ordinal location of this <see cref="Category"/>
///     relative to other listed <see cref="Category"/> tags.
/// </summary>

However, if you simply must pluralize the tag, do it this way:

///     relative to other listed <see cref="Category"/>s.

Never use an apostrophe to pluralize. Apostrophes are for contractions and possession only. (Well, that depends on your usage; I've always thought of it as improper, but I guess that's subjective. See here.)

3
  • What about 2's and 3's? Symbols also use apostrophes. That was my thinking that the type ("Category") was like a symbol. And "Categorys" is not a word.
    – Jordan
    Feb 16, 2011 at 21:34
  • 3
    I disagree that "2's" and "3's" is proper; I prefer "2s" and "3s".
    – Andrew
    Feb 16, 2011 at 21:44
  • Although now that I think about it even "twos" and "threes" are preferable to either. Pluralizing things that aren't natural written-out English words is tricky and prone to awkwardness and errors and just isn't worth it.
    – Andrew
    Feb 17, 2011 at 14:49
2
/// <summary>
///     Order - Identifies the ordinal location of the <see> node
///     relative to other listed <see> nodes.
/// </summary>

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.