.NET XML Comment Cheat Sheet
May 19, 2009
Update: Ghost doc (free addin for Visual Studio 2008) makes a lot of the snippets redundent. Some are still relevant however.
If you like to give your code meaningful XML comments and want the output to look vaguely like the MSDN documentation, then below are a few templates you can use for consistency. These aren’t “how to write XX method” but just how the textual descriptions appear in most of the .NET framework documentation, for example you’ll find ‘Raises the … event’ in almost all event descriptions.
The download above the examples below in snippet format (for VS.NET 2005/2008) that autocompletes various methods. To use the .snippet download, copy it to your ‘C:\Users\Documents\Visual Studio 2008\Code Snippets\Visual C#’ directory and then type eqts inside the code editor in Visual Studio.
Make sure you click ‘view plain’ to get the properly formatted text, as some lines span over the textarea.
Embedding tags
If you need to put a tag inside you description use HTML/XML coding. There’s no need to do this for CDATA.
< >
New Paragraphs
You will need to wrap descriptions in these tags if you want it to be readable instead of a wall of text.
<para></para>
Standard constructor
/// <summary> /// Initializes a new instance of the <see cref="MyClass">MyClass</see> class. /// </summary>
Standard event and raising the event
/// <summary>
/// Occurs when the page is process is complete.
/// </summary>
public event EventHandler Complete;
/// <summary>
/// Raises the <see cref="Complete">Complete</see> event.
/// </summary>
/// <param name="e">An <see cref="EventArgs">EventArgs</see> object that contains the event data.</param>
protected virtual void OnComplete(EventArgs e)
{
if (Complete != null)
Complete(this, e);
}
Embedding links to other classes, properties, methods
Update: The latest Sandcastle build now works with links without having to specify the name inside the see tag’s content.
<summary> Go on, have a look at <see cref="MyClass"/> Go on, have a look at <see cref="MyClass.MyMethod"/> and Go on, have a look at <see cref="MyClass.MyProperty">Custom text</see> </summary>
Embedding an example
Remember to use CDATA or you’ll get documentation errors.
/// <example> /// Below is an example of using MyMethod to do something. /// <code> /// <![CDATA[ /// MyClass a = new MyClass(); /// string result = a.MyMethod(); /// ]]> /// </code> /// </example>
Linking to external documentation
From another file (for large amounts of documentation that makes it hard to read the source file)
<include file="blah.xml" path="/documentation/members[@Name='Class1']"/>
The XML file would be:
<?xml version="1.0" encoding="utf-8" ?> <documentation> <members name="Class1"> <summary> All the usual XML tags here. </summary> </members> <members name="Class2"> <summary> etc. </summary> </members> </documentation>
Throwing exceptions
The deliberate design decision to remove the forcing of exception handling chains like in Java is in my view one of the major pluses of C# over Java. The idea is to place it in documentation instead. Unfortunately it’s not really kept to (most programmers don’t like to document as a feeling of completeness like I do, which for time constraints is my weak point).
/// <exception cref="InvalidOperationException"> /// Here you describe why the exception will be thrown. /// </exception>
Exception class headers
/// <summary> /// Initializes a new instance of the <see cref="MyException">MyException</see> class using the /// specified message and inner exception. /// </summary> /// <param name="message">The error message that explains the reason for the exception.</param> /// <param name="innerException">The exception that is the cause of the current exception. If the innerException parameter is not a null reference, the current exception is raised in a catch block that handles the inner exception.</param>
Overriding Hashcode
In the written style of MSDN documentation
/// <summary> /// Computes and retrieves a hash code for an object. /// </summary> /// <remarks> /// This method implements the <see cref="Object">Object</see> method. /// </remarks> /// <returns>A hash code for an object.</returns>
Overriding ToString
In the written style of MSDN documentation
/// <summary> /// Displays information about the <c>Field</c> in readable format. /// </summary> /// <returns>A string representation of the object.</returns>
Overriding Equals
In the written style of MSDN documentation
/// <summary> /// Determines whether two <see ref="X">X</see> objects are equal. /// </summary> /// <remarks> /// For the two <see ref="X">X</see> objects to be equal, they must have the same Number. /// </remarks> /// <param name="obj">The <see ref="X">X</see> object to compare to the current <see ref="X">X</see>.</param> /// <returns>True if the specified <see ref="X">X</see> is equal to the current <see ref="X">X</see>; otherwise false.</returns>
Links
I'm Chris Small, a software engineer working in London. This is my tech blog. Find out more about me via Github, Stackoverflow, Resume