(How)
C^# You Are - 18 February 2007

XML Documentation Comments - You can refer to my Documentation Summary guidelines in the Downloads section for the full syntax along with my personal commenting recommendations.  Note that this syntax is supported by both C# and VB.NET (v2+).

1. What tag should all publicly accessible members of a type have?  Answer

   The <summary> tag.  This tag provides a one or two line description of every member of every type including properties, fields and methods.  Additionally types like classes, interfaces, structures, enumerations and enumeration values should also use this tag.  This tag is used to provide summary information when the element is displayed in the documentation. 

   <summary>Provides extended support for collections of objects.</summary>
   public class CollectionEx<T> : Collection<T>
   

   
   
2. How do you document generic type parameters in the documentation?  Answer

   Use the <typeparam> tag to document the purpose of the type parameter.  Use the <typeparmref> tag to reference a generic type parameter.

   <summary>Provides extended support for collections of objects.</summary>
   <typeparam name="T">The type of the objects stored in the collection.</typeparam>
   <remarks>
   ...
   <typeparamref name="T"> will contain its default value.
   </remarks>
   public class CollectionEx<T> : Collection<T>
   

   
   
3. How do you refer to other types or members in documentation?  Answer

   To reference other types and members within paragraph tags like the summary or remarks sections use <see>.  To add a reference in the See Also section use the tag <seealso> outside of any paragraph tag.  Note that under VS 2003 this tag would only appear within a remarks section but it must, in fact, reside outside a paragraph tag.

   <summary>Provides extended support for collections of objects.</summary>
   <remarks>
   This class extends <see cref="Collection`1/> to include some additional helper routines.
   </remarks>
   <seealso cref="DictionaryEx`1/>
   public class CollectionEx<T> : Collection<T>
   

   
   
4. How do you refer to generic methods or types in documentation tags?  Answer

   You can use one of two syntaxes.  The first syntax uses the format-style layout of wrapping the type name in curly braces.

   <summary>Provides extended support for collections of objects.</summary>
   <seealso cref="DictionaryEx{T}"/>
   public class CollectionEx<T> : Collection<T>
   

   
   

   The second format uses a tick followed by the generic parameter number (starting at one).

   <summary>Provides extended support for collections of objects.</summary>
   <seealso cref="DictionaryEx`1"/>
   public class CollectionEx<T> : Collection<T>
   

   
   
5. How do you create a list of items in documentation?  Answer

   The <list> element can be used to generate a table, numbered list or bulleted list of items.  For bulleted or numbered lists use the <item> tag for each list member.

   <list type="bullet">
      <item>Item 1</item>
      <item>Item 2</item>
   </list>
   

   
   

   For tables use <listheader> to define the table column headers and <item> along with <term> and optionally <description> for each row of the table.

   <list type="table">
      <listheader>
         <term>Returns</term>
         <description>Meaning</description>
      </listheader>
      <item>
         <term>0</term>
         <description>The items are equal.</description>
      </item>
      <item>
         <term>Positive</term>
         <description>Item 1 is greater than item 2.</description>
      </item>
      <item>
         <term>Negative</term>
         <description>Item 1 is less than item 2.</description>
      </item>
   </list>
   

   
   
6. How do you include greater than or less than signs in documentation comments?  Answer

   The documentation comments are standard XML so you will use standard XML tags like gt; for greater than and lt; for less than.

7. How do you generate comments, like MSDN, where language-specific keywords are replaced with the language-appropriate keywords.  For example in MSDN you will see null values refered to as null reference (Nothing in Visual Basic)?  Answer

   Actually the built in commenting style does not support this.  However NDoc, which was the predominant documentation generator for v1.x of .NET, and now SandCastle, Microsoft's own documentation generator, extended the syntax of the <see> tag to support language keywords like null.  You will use the attribute langword in lieu of the cref attribute.

   <remarks>
   The value can not be <see langword="null"/> or else an exception will be thrown.
   </remarks> 

   
   
8. How do you create language-specific examples in documentation?  Answer

   You use the tag <example> to define a block of example code.  You then use the <code> block to create a specific block of code.  The built in commenting style does not support language-specific code blocks.  NDoc extended <code> to include a lang attribute that allowed you to specify the language exposed by the code block.  In theory this would allow the documentation browser to filter out examples that did not match the language filter set by the user.  At this time support is partially available in SandCastle.

   <example>
   <code lang="C#">
   Collection<string> strings = new Collection<string>();
   </code>
   <code lang="VB">
   Dim strings As New Collection(Of String)
   </code>
   </example>

   
   
9. How do you document exceptions?  Answer

   Use the <exception>tag.  The tag should document under what conditions the exception will be raised.  The exceptions are combined together in a separate section in the final documentation.

   <exception cref="ArgumentNullException"><paramref name="key"/> is <see langword="null"/>.</exception>
   <exception cref="ArgumentException"><paramref name="key"/> is empty or invalid.</exception>
   

   
   
10. What does the <include> tag do?  Answer

    This tag allows you to move the documentation elements to a separate file and include the documentation, including the XPath path to the element, in your source files.