Jelle Druyts

I'll come out and bluntly admit it: I don't mind writing XML comments in my code. Really. I can get pretty freaky about it too if you let me, and I always try to make sure that every comment is kept in sync with the code it's covering. Why? Because if you make the compiler (or a 3rd party tool for those languages that don't support it) emit an XML comments file, it gives you free and up-to-date IntelliSense and even full-blown technical documentation, duh!

So if you're also constantly lost in the MSDN documentation trying to figure out which tags are allowed and what the syntax is, here's a quick reference for your amusement. Now start writing comments, please!

Documentation Sections

• <summary>
  
  A short description of the item; describe the members of the type here.
  
  <summary>text</summary>
  
  
• <remarks>
  
  The "Remarks" section of the documentation; specify overview information here.
  
  <remarks>text</remarks>
  
  
• <example>
  
  The "Example" section of the documentation.
  
  <example>text</example>
  
  
• <seealso>
  
  A link in the "See Also" section of the documentation.
  
  <seealso cref="member">text</seealso>
  

Member Documentation

• <param>
  
  Describes a parameter to a method.
  
  <param name="name">text</param>
  
  
• <returns>
  
  The return value of a method.
  
  <returns>text</returns>
  
  
• <exception>
  
  The exceptions that can be thrown.
  
  <exception [cref="type"]>text</exception>
  
  
• <value>
  
  Describes the value of a property.
  
  <value>text</value>
  
  
• <permission>
  
  The permission applied to a member.
  
  <permission [cref="type"]>text</permission>
  

Text Formatting

• <c>
  
  Format characters as code within other text.
  
  <c>code</c>
  
  
• <code>
  
  Multiline section of code.
  
  <code>code</code>
  
  
• <see cref>
  
  A link to a type, member or field in the current compilation environment.
  
  <see cref="member">text</see>
  
  
• <see langword>
  
  Undocumented. A link to a keyword in the language of the current compilation environment, e.g. null.
  
  <see langword="keyword"/>
  
  
• <paramref>
  
  A reference to a parameter within other text.
  
  <paramref name="name"/>
  
  
• <list>
  
  A list of items.
  
  <list type="[bullet|number|table]">
      <listheader>
          <term>name</term>
          <description>text</description>
      </listheader>
      <item>
          <term>name</term>
          <description>text</description>
      </item>
  </list>
  
  
• <para>
  
  A paragraph within other text.
  
  <para>text</para>
  
  
• <include>
  
  Refer to comments in another file.
  
  <include file='filename' path='tagpath[@name="id"]' />