C# XML Comments: How many <see ... /> references in XML comments are useful?
c#, comments, xml
Solution
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.
Problem
In our company we write excessive Xml comments. A typical method is has to be documented like this: ``` /// <summary> /// Determines whether this <see cref="IScheduler"/> contains a specific <see cref="ISchedule"/>. /// </summary> /// <param name="schedule">The <see cref="ISchedule"/> to locate in this <see cref="IScheduler"/>.</param> /// <returns> /// Returns <see langword="true"/> if <paramref name="schedule"/> is found in this <see cref="IScheduler"/>; otherwise, <see langword="false"/>. /// </returns> bool Contains(ISchedule schedule); /// <summary> /// Removes and <see cref="IDisposable.Dispose"/>s the first occurrence of a specific <see cref="ISchedule"/> /// from this <see cref="IScheduler"/>. /// </summary> /// <param name="schedule">The <see cref="ISchedule"/> to remove from this <see cref="IScheduler"/>.</param> /// <exception cref="System.ArgumentNullException">Is thrown when the parameter schedule is null.</exception> /// <exception cref="System.ArgumentException">Is thrown when the <see cref="ISchedule"/> is not found in this <see cref="IScheduler"/> or was of the wrong type.</exception> void Remove(ISchedule schedule); ``` As you can see nearly every noun which can be referenced using a `<see cref>` tag. I find this too much. Most of our code files are so blown up with such comments. Makes the comments section nearly unreadable. What do you think? Do you like this kind of documentation in the code or not? As usual I think there is no black / white answer to such a kind of question, that's why I made it wiki. EDIT: My question was not if the see-ref-tags itself are useful per default. It is clear that the generated links in the .chm file (or any other kind of generated docu) are very useful. My question was if it's is really useful to tag every occurrence of every "linkable" noun in the comments. We use Sandcastle to generate the docu every night. Unfortunately it is very rarly used by other developers, but that's another issue.