Comments and code constructs

As already mentioned any template that you use to start a project generally already has lots of default XML documentation – including sections of generated code that you probably never give a moment’s thought to.

If you look carefully at the file however you should be able to find the documentation that you added:

<member name="M:WindowsFormsApplication1.
                         Form1.MyMethod">
 <summary>
  MyMethod is designed to
  demonstrate XML documentation
 </summary>
</member>

You can see immediately the structure of the XML goes a little further than you might have expected. As well as the <summary> tags that were in the triple slash comments there is also a pair of <member> tags with a name attribute giving the fully qualified name of the method that the <summary> tags are associated with.

The idea that every comment is associated with a particular code construct – a method in our example – is also key to understanding how it all works.

You can only add a comment to one of:

class, struct, enum, method, property, field indexer, delegate or event.

Any triple slash comments not associated with one of these constructs is simply ignored by the XML generator. If you start a triple slash comment that is in the wrong place, i.e. not associated with a correct code construct, then the IDE will not auto-generate a pair of <summary> tags for you. If you are in the correct place than not only will the IDE generate a pair of tags but it also generates the name of the code construct and indicates its type with a leading letter followed by a colon.

This name is used at the value of the name attribute in the <member> tag. Hence:

<member name="M:WindowsFormsApplication1.
                         Form1.MyMethod">
 <summary>
  MyMethod is designed to
  demonstrate XML documentation
 </summary>
</member>

and the “M:” means Method. Other single letter type indicators include:

• N: =Namespace
• T:=Type i.e. class, interface, struct, enum or delegate
• F:=Field
• P: Property
• E: Event
• I: error unresolved construct.

In addition to these indicators methods are also documented with additional information.

For any method that has parameters a <param> tag listing the parameter names as attribute values is added. For example:

/// <summary>
/// MyMethod is designed to
/// demonstrate XML documentation
/// </summary>
/// <param name="param1">
///    A simple integer
///    </param>
/// <param name="param2">
///    A more sophisticated string
/// </param>
///  

public void MyMethod(int param1,
                          string param2)
{
}

<member name="M:WindowsFormsApplication1.
  Form1.MyMethod(
         System.Int32,System.String)">
 <summary>
  MyMethod is designed to
  demonstrate XML documentation
 </summary>
 <param name="param1">
  A simple integer
 </param>
 <param name="param2">
  A more sophisticated string
 </param>
</member>

Notice that in addition to the <param> tags the parameter types have been added to the name attribute.

Similarly for any non-void return type the IDE generates a <return> tag so that you can comment on the purpose of the returned value. Notice that the type of the return value isn’t automatically encoded. The only exception to this if for an implicit conversion operator when the return type is coded as part of the name following “~”.

<ASIN:0764588451>

<ASIN:0596007124>