XML Comment Cheat Sheet
.NET XML Documentation guide + cheat sheet

• Home
• ›
• Code snippets
• ›
• C#
• ›
• XML Comment Cheat Sheet

Download .snippet files for these examples

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. 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
<summary> Go on, have a look at <see cref="MyClass">MyClass</see> </summary> Embedding links to other class properties/methods
<summary> Go on, have a look at <see cref="MyClass.MyMethod">MyMethod</see> and Go on, have a look at <see cref="MyClass.MyProperty">MyProperty</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']"/> then 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> Your method catches an exception
/// <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
As found in MSDN /// <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
As found in MSDN /// <summary> /// Displays information about the <c>Field</c> in readable format. /// </summary> /// <returns>A string representation of the object.</returns> Overriding Equals
As found in MSDN /// <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
Sandcastle for building web/htmlhelp documentation from the .xml files
GUI for Sandcastle
MSDN docs for .NET XML documentation (local)
MSDN docs for .NET XML documentation (online)

---

› Home
› C#
› Snippets
› Articles
› Tools
› Taglines
› ASP
› Dictionary Object
› FSO
› Unix cheat sheet
› Gaming
› CSS
› Yak
› Umbraco
› About
› Contact
› Privacy
› Projects
› Search