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

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


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.


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.


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.