CSharp In-Code Documentation with MS XML Tags

From OpenPetra Wiki
Jump to navigation Jump to search


In C#, documentation for code can be created by including XML tags in special comment fields in the source code directly before the code block they refer to.

We should strive to document all openPETRA code with this kind of code comments because they...

  1. help us programmers understand (our or others') code better;
  2. follow an .NET industry-wide agreed documentation standard;
  3. allow fairly automatic production of API-style documentation that is very similar to the appearance of the .NET Framework documentation on MSDN.

Note: The XML doc comments are not metadata; they are not included in the compiled assembly and therefore they are not accessible through reflection.

XML Documentation Comments: How-To



<codepre> /// <summary>

/// This class...

/// </summary> </codepre>

Multiline XML comments follow this pattern:

<codepre> /// <exception cref=”BogusException”>

/// This exception gets thrown as soon as a

/// Bogus flag gets set.

/// </exception> </codepre>

All lines must be preceded by /// (three slashes) to be accepted as XML comment lines.

The following links lead to pages where more information about XML Documentation Tags and more examples can be found: