Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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.

share|improve this question

3 Answers 3

up vote 4 down vote accepted

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.

share|improve this answer
    
That is exactly what I was looking for. :) –  Jordan Jun 21 '11 at 13:23

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.)

share|improve this answer
    
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 '11 at 21:34
3  
I disagree that "2's" and "3's" is proper; I prefer "2s" and "3s". –  Andrew Arnold Feb 16 '11 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 Arnold Feb 17 '11 at 14:49
/// <summary>
///     Order - Identifies the ordinal location of the <see> node
///     relative to other listed <see> nodes.
/// </summary>
share|improve this answer

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

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