Geek Answers Handbook

Are there any published styles for C # XML documentation?

I ask my developers to write C # code to follow the recommendations of StyleCop. This is great for code, but I almost always have questions about documentation (fine ... ok ... so no one asks because programmers tend to hate documentation). I might suggest copying the MSDN style, but I'm curious if Microsoft or anyone else has posted anything 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 am not trying to provoke a discussion about how to write documentation. I am looking for some published guidelines on the proposed documentation syntax.

Thanks in advance!

+6
c # documentation
source share
3 answers

StyleCop FxCop actually provides rules for XML documentation. If you do not follow the pattern specified by a specific set of rules, he will complain.

These are all the rules of SA1600-SA1647.

For example, rule SA1642: ConstructorSummaryDocumentationMustBeginWithStandardText states that:

A summary for a non-private instance constructor should begin with "Initializes a new instance of the class {class name}".

For more information, see FxCop .

+7
source share

If you want a general guide on how and where to use the XML documentation, the following two useful links (which I have repeatedly referred to).

I guess this is vague what you are looking for. As for the actual wording and grammar of the XML comments, I also looked for recommendations / recommendations on this subject, but to no avail. The best idea in this regard is to simply follow the .NET BCL (Base Class Library) - although there is an odd inconsistency even in the BCL documentation.

Hope this helps ...

+3
source share

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

It has a set of templates that allow you to specify the exact style (which records are legal for different types of code elements, in what order they are indicated, whether there are empty lines between certain elements and the style of the attached documentation block). It will delete entries that are no longer valid (for example, delete parameters), and add entries for undocumented functions (for example, new parameters or abandoned exceptions), and it will keep the documentation in order using automatic indentation and word wrap.

Thus, using the AU to generate and update your comments, you can very easily provide a specific style and layout for your documentation comments. If you want to use StyleCop to enforce certain documentation rules, AtomineerUtils has the ability to create documentation in a format compatible with StyleCop.

It also makes it so quick and easy to document code that even less desirable programmers on your team will document their code much better.

+2
source share

More articles:


All Articles