Manual Documentation

At this point it is important to understand that the IDE is inserting tags as it thinks fit but you can do the same job manually if you want to.

As long as you insert valid XML the compiler will add it to the XML file it generates. You can even invent your own tags to do special tasks.

However the compiler actually checks the correctness of some of the tags that are generated automatically and their content is used in Intellisense prompting.

For example, with the documentation given for MyMethod listed above you will see the content of the  <summary> tag part way through typing MyMethod( and the parameter tag value after typing the opening bracket.

This makes this approach to documenting class libraries immediately rewarding – even to the programmer creating the documentation!

There are some other tags that are only entered manually that are worth knowing about.

In particular if you want to make an extended remark about a code construct then use the <remarks> tag.

Use the <see> and <seealso> tags to refer to other constructs that are relevant to the current constructs.

Perhaps the most elaborate of the standard tags is the <example> tag which can be used, as its name suggests, to provide an example of the use of the construct complete with code.

To include code you either need to use the <c> tag for code snippets or <code> for multi-line code examples. 

For example:

/// <remarks>
///  This method is very clever and 
///  I'm very proud of it 
///  so pay special attention
///  when you read it.
/// </remarks>
/// <example>
///  To call this method:
///  <code>
///   MyMethod(1,"String");
///  </code>
/// </example>

Which generates:

<remarks>
 This method is very clever and 
 I'm very proud of it 
 so pay special attention
 when you read it.
</remarks>
<example>
  To call this method:
 <code>
  MyMethod(1,"String");
 </code>
</example>

It is important to realise that there is no implied semantics here.

The text in between the <code> tags is just text. The value of all of this really only comes about when the XML is put through some sort of processor which treats the values associated with each tag appropriately e.g. formatting and colour coding anything between <code> tags.

For example, the <list> tag can be used to include a list of items formatted as bullet, numeric or as a table according to the type attribute specified. However if you try:

/// <list type="bullet">
///  <term>
///   bug number 1
///  </term>
///  <term>
///   bug number 2
///  </term>
/// </list>

then when this is converted to XML you don’t see any bullet points just the usual tags:

<list type="bullet">
 <term>bug number 1</term>
 <term>bug number 2</term>
</list>

So what is the point of using type=“bullet” or indeed any of the recommended tags?

The XML generated by the compiler is intended to be further processed by a documentation engine of some kind and if you use these standard tags then there is a reasonable chance that the engine will format things as you expect. If you use non-standard tags then processing the XML is your problem – more of which later.

Cref

One final comment on tags and meaning: a commonly used attribute cref is a little confusing.

The documentation says that some tags can use cref to create a link to other members but what does this mean?

For example the <see> and <seealso> tags have a cref to specify what additional documentation the user should consult. The attribute works by simply specifying the name of a member as generated by the IDE. You do this by simply giving an unambiguous name of the member and the compiler transforms this to the fully qualified name complete with single letter type identifier.

For example:

/// <see cref="MyMethod"/>

is translated to:

<see cref=
"M:WindowsFormsApplication1.Form1.
  MyMethod(
    System.Int32,System.String)" />

Obviously it is better to give a more specific name within the cref to avoid any later changes altering the documentation for example:

/// <see cref="Form1.MyMethod"/>

If the compiler cannot find the member specified then it will generate an error which means you can’t refer to members that don’t yet exist.

Once again the XML that is generated has no predefined semantics but you can expect documentation processing tools to convert it to something like a hyperlink to other areas of the documentation.

It is also worth knowing that the compiler will allow you to use curly brackets in place of angle brackets in generic types so as to avoid confusion with XML tags.

For example:

/// <see cref="List{T}"/>

is converted to System.Collections.Generic.List<T>.

<ASIN:0495806439>

<ASIN:193435645X>