Are there published style guidelines for C# XML documentation?

Question

I ask my developers who write C# code to follow StyleCop's guidelines. It's great for code, but I almost always have questions about documentation (ok...ok...so no one asks, because programmers tend to hate documentation) style. I could suggest copying MSDN's style, but I'm curious whether Microsoft or someone else has published something about this.

For Example, constructors are documented as follows.

/// <summary>
/// Initializes a new instance of <c>MyClass</c> using the specified <c>BaseMyClass</c>.
/// </summary>
/// <param name="myParam">The <c>MyParam</c> of the current session.</param>

I'm not trying to spark a debate over how documentation should be written, here. I'm looking for some kind of published guidelines about the suggested syntax for documentation.

Thanks in advance!

Answer 1

StyleCop actually provides rules for XML documentation, as well. If you don't follow it's patterns, it will complain.

These are all rules SA1600-SA1647.

For example, rule SA1642: ConstructorSummaryDocumentationMustBeginWithStandardText states that :

The summary for a non-private instance constructor must begin with “Initializes a new instance of the {class name} class.”

The rules are all listed in the rules documentation, downloadable here.

Answer 2

If you want a general guide to how and where XML documentation should be used, the following are two highly useful links (to which I have referred on many occasions).

• MSDN Recommended Tags for Documentation Comments
• C# XML Documentation : Alan Dean

I assume this is vaguely the sort of thing you're looking for. Regarding the actual phrasing and grammar of XML comments, I too searched for advice/guidelines on that, but to no avail. Best idea in this respect is simply to follow the .NET BCL (Base Class Library) - though there is the odd inconsistency even in BCL documentation.

Hope that helps...

Answer 3

My visual studio add-in, AtomineerUtils, will generate and update XmlDoc comments.

It has a set of templates that allow you to specify the exact style (which entries are legal for different types of code element, which order they are listed, whether there are blank lines between certain entries, and the style of the enclosing documentation block). It will remove entries that are no longer correct (e.g. delete parameters) and add entries for undocumented features (e.g. new parameters or thrown exceptions), and it'll keep the documentation tidy using automated indentation and word wrapping.

So by using AU to generate and update your comments, you can very easily enforce a specific style and layout for your documentation comments.

It also makes it so quick and easy to document code that even the less willing programmers in your team will be much more likely to document their code well.