Difference between revisions of "CSharp In-Code Documentation with MS XML Tags"

From OpenPetra Wiki
Jump to navigation Jump to search
(Created page with '== 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. …')
 
 
(One intermediate revision by the same user not shown)
Line 2: Line 2:
 
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.
 
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...
+
'''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;
 
# help us programmers understand (our or others') code better;
 
# follow an .NET industry-wide agreed documentation standard;
 
# follow an .NET industry-wide agreed documentation standard;
Line 20: Line 20:
  
 
=== Examples ===
 
=== Examples ===
<codepre>
+
/// <summary>
/// <summary>
+
/// This class...
 
+
/// </summary>
/// This class...
 
 
 
/// </summary>
 
</codepre>
 
  
 
Multiline XML comments follow this pattern:
 
Multiline XML comments follow this pattern:
  
<codepre>
+
/// <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>
 
</codepre>
 
  
 
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 16: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...

  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

Overviews

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: