CSharp In-Code Documentation with MS XML Tags: Difference between revisions
Jump to navigation
Jump to search
No edit summary |
|||
Line 20: | Line 20: | ||
=== Examples === | === Examples === | ||
/// <summary> | |||
/// <summary> | /// This class... | ||
/// </summary> | |||
/// This class... | |||
/// </summary | |||
Multiline XML comments follow this pattern: | Multiline XML comments follow this pattern: | ||
/// <exception cref=”BogusException”> | |||
/// <exception cref=”BogusException”> | /// This exception gets thrown as soon as a | ||
/// Bogus flag gets set. | |||
/// This exception gets thrown as soon as a | /// </exception> | ||
/// Bogus flag gets set. | |||
/// </exception | |||
All lines must be preceded by <code>///</code> (three slashes) to be accepted as XML comment lines. | All lines must be preceded by <code>///</code> (three slashes) to be accepted as XML comment lines. |
Latest revision as of 15:47, 15 July 2010
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 openPETRA 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
/// <summary> /// This class... /// </summary>
Multiline XML comments follow this pattern:
/// <exception cref=”BogusException”> /// This exception gets thrown as soon as a /// Bogus flag gets set. /// </exception>
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: