Applied C# Xml Documentation

The article is devoted to the problems of quality documentation and ways you can cut time on doing this undoubtedly very useful job. You can let the application generate the documentation for you. How? Please read in the article.

Documentation for software applications: quality criteria

Do you write technical documentation for the project? No, because you still think this is a waste of time? As I faced repeatedly with a lack of technical documentation for the project or its poor quality, I decided to conduct some research. I assumed that:

• writing technical documentation is a must,
• documentation process should be as simple as possible,
• documentation should be complementary to the code, rather than clarify it,
• it should remain relevant in the process of modernizing the code,
• and have a readable form, to be structured.

Automatic documentation generation: how to do?

Our department writes in C# using Visual Studio 2005 / 2008 as a development environment that automatically enables us to adopt a ready means of documenting the rich code - XML Documentation. (I’d like to admit to be fair that there exist a lot of document generators - for different platforms and different programming languages, here is a comparative overview of some of them.) On the Internet, I came across an excellent article of Alan Dean "C# Xml Documentation" which detailed a process of adding xml documentation to the project, as well as a full review of existing standard xml tags with examples of their use. I have reviewed all of these tags, and roughly divided them into three categories: for mandatory, desirable use, and almost unnecessary. And I consciously strive to narrow the range of mandatory and desirable tags. I got the table like this:  

  The toolbox has shrunk to 6 tags. And with those remaining need to adhere to the following important rule: «If you can avoid using the tag - do not use it!». Do not clog xml documentation with redundant information – it becomes unreadable, complicates the process of editing, which in turn increases the risk that documentation ceases to be valid. Once again: «If you can avoid using the tag - do not use it!». In addition, the private members of the class do not need comments at all.

    1.  Often, the only tag used. In the vast majority of cases, this tag is enough to describe appointment of a class / method / field etc. A very important rule is that within the summary there should be written text only. No nested tags! The only exception is, perhaps, tag . For example, the temptation is great to use inside of a tag, because in the generated documentation tag will be translated into a link. Don’t do this. First, because when you change the class name, link will cease to be valid and the compiler won’t tell you about this, and secondly, because the content oftag appears in the contextual help in Visual Studio editor and a full class name with all the namespaces will look messy. Wrong:

///<summary>
/// Returns <see cref="Organization.App.BL.Domain.Movie" /> by the specified movie id.
///</summary>

Right:

///<summary>
/// Returns movie by the specified movie id.
///</summary>

 It is very important to try to withstand the commentary in the same style. All the methods I comment using pattern [step] [key features]:

///<summary>
/// Deletes movie with a a specified id from the database.
///</summary>
public void DeleteMovie(Guid movieId)

  My pattern for the constructors is "Initializes new instance of [...] using [...]:

///<summary>
/// Initializes new instance of MailManager using specified culture.
///</summary>

 public MailManager(CultureInfo culture) Comments for the properties I start with keywords “Gets or sets”:

///<summary>
/// Gets or sets movie name.
///</summary>
public string Name { get; set; }
///<summary>
/// Gets value indicating whether movie is valid.
///</summary>
public bool IsValid { get; }

    2. It is always a pleasure, when the method warns you about what the exceptional situation it can provoke. It is a pity only that a programmer has to populate exceptions list manually - the compiler is not following the relevance of the list. Therefore, use tag with caution, because provided information may not correspond to reality. With this in mind, I use tag rarely, only when I am sure that the method will not change frequently.

    3. Use the tag only when the parameters put forward any special requirements that are worth mentioning.

///<summary>
/// Returns pixel with a specified coordinates.
///</summary>
///<param name="x">Non-negative x-coordinate of pixel.</param>
///<param name="y">Non-negative y-coordinate of pixel.</param>
///<returns></returns>
public object GetPixel(int x, int y)

  In this example, 2 requirements being put forward - x and y must be nonnegative. Incidentally, in this example usage of tag is more then appropriate, right?

    4. This tag should be followed by tag. It is welcoming the use of nested tags and in the tag. Moreover, if you do not use and tags inside tag, than whole tag is probably is not needed.

    5. These tags can only be used inside the tag . As with the tag the compiler will not monitor the accuracy of your references, so use the tags and very carefully, and preferably do not use them at all. It is easy to follow a rule - immediately after the definition of some entity (class, method, etc) write a for it. Sometimes during the process of writing for a method, I come to the conclusion that this method is not needed. True - if I can not write a for a method, I do not understand its appointment. This is kind of an early application architecture diagnosing. I have described only a set of standard tags. But there are tools that can process additional set of commentary tags (xml is extensible). Following markup makes Sandcastle Help File Builder to insert into the resulting document code snippet from the file: By the way, MSDN was generated using Sandcastle. In general, writing documentation is like walking on blade’s age (sorry for the pathos) - on the one hand it is bad when documentation is poor, on the other hand it is bad when documentation process hardens application development process. But there always is a golden middle way. Eugene T., .NET team, Binary Studio