CSharp In-Code Documentation with MS XML Tags
Introduction
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 Petra.NET code with this kind of code comments because they...
- help us programmers understand (our or others') code better;
- follow an .NET industry-wide agreed documentation standard;
- 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
Overviews
- XML Documentation Comments (MS)
- Short introduction with links to detail articles
- Documenting C# source code with XML Comments
- Provides good overview and some hints.
- XML Documentation Comments Guide
- Very comprehensive! Includes information about specific tags that are supported by Sandcastle through Sandcastle Help File Builder, which we use.
Examples
<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: