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

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. …')
 
No edit summary
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;

Revision as of 15:46, 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

<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: