C# XML Comments: How many <see ... /> references in XML comments are useful ?

Answer 1

The point of all of those is that when something like Sandcastle is used to generate HTML or CHM docs for the library, that those docs get hyperlinked navigation between objects. So the question then is, when you use MSDN do you find it useful to be able to click on a class name a have it navigate to the help for that class, or are you ok with copying it and pasting it into the search field?

Yes, it bloats the code (though comments can be collapsed), but if you actually ship documentation to others, it's pretty darned helpful.

Answer 2

There is a particular reason for these sorts of comments: they can be used to generate documentation or to add extra information to autocomplete. I agree that they are overly verbose and difficult to read for most situations, but they are good to add to an interface which you are going to expose externally.

I would recommend using an editor which allows you to turn comments on and off.

Some languages allow you to store comments as metadata on variables and functions, which is a nice alternative.

Answer 3

Personally, I think what you have is a bit overboard.

The purpose of the "see" references is to provide good linking between topics in the generated help documentation after parsing.

In your case, your business-specific libraries are referencing language items, ie:

<see langword="true"/>

I personally feel that hyperlinks to other related objects in your library is a very useful feature. It makes reading the help much more usable for your users.

Hyperlinks to language elements is something that I feel should only exist inside the language help itself. In the case of a third party library, this just "muddles" up the message by putting links everywhere. This makes the good links less effective, since they get hidden in the mess.

I would suggest liberal use of linking to related classes in your library. I would avoid adding hyperlinks to base library classes, except in specific instances where it is particularly useful for some reason (rare). Linking to "true" and "IDisposable.Dispose", etc, doesn't really add a lot of value.

Trust your user to understand the base framework, but teach them about your library.

Answer 4

As ctacke said, it's very useful for hyperlinking. However, if you're not actually shipping documentation, all that tagging makes the documentation virtually impossible to read. In that case, the documentation is for the (edit: INTERNAL) developer, and if he or she can't read it, you're wasting your time.

As a rule, I tend to the first reference to a type or member, and leave the rest unlinked. It leaves the comments pretty clean, and still provides meaningful linking.

Answer 5

When you're working with Visual Studio, then you can use the CR_Documentor plugin (it's free, you can get it here) for WYSiWYG-reading/writing your comments. It looks like generated help form Sandcastle or NDoc, but is rendered on the fly. It's really useful, and you don't have to care about the raw xml comments at all.