Hiding the comments

One of the problems with adding XML comments to source code is that they can obscure the code itself.

The simplest solution to this problem is to use outlining to collapse the XML comments using the outliner and only expand when needed. However this doesn’t help with the problem of allowing two users to work on the same code – one modifying the code and one documenting.

The solution to this problem is to use the <include> tag which instructs the compiler to read the contents of an external file as XML to be used as comments.

Of course you now need some way to associate the XML in the file with the various members in the code. This is achieved by specifying which XML tags are to be extracted from the file at the point that the <include> tag is used.

That is the position of the <include> tag specifies where in the code the XML comments are to be inserted and hence which member they apply to. To specify which chunk of XML in the file is to be applied to the member we have to use an XPATH specification selecting that XML.

So for example, if we have an XML file called XMLFile1.xml that contains the XML needed to comment MyMethod you might use and <include> of the form:

/// <include file='XMLFile1.xml' 
                            path='/*'/>
public void MyMethod(int param1,
                          string param2)
{
}

Obviously the file attribute specifies the XML file. Less obviously the path attribute is an XPATH statement that locates the XML in the file to be used. In this case the XPATH simply resolves to everything inside the root tags.

In this case if the XML file contained the following:

<?xml version="1.0" encoding="utf-8" ?>
<MyDocs>
 <summary>
  MyMethod is designed to
  demonstrate XMLx documentation
 </summary>
</MyDocs>

The XPATH specification retrieves everything from the root of the XML tree and  hence inserts the <summary> tags.

The compiler then generates:

<member name= "M:WindowsFormsApplication1.
       Form1.MyMethod(
          System.Int32,System.String)">
 <summary>
  MyMethod is designed to
  demonstrate XML documentation
 </summary>
</member>

Clearly you can’t use this approach if you are going to want to include the XML to document multiple members within a single file. In this case the solution is to add additional XML tags to allow XPATH expressions to be written to select which XML subtree is to be used for each <include> tag.

For example, if the XML file contains

<?xml version="1.0" encoding="utf-8" ?>
 <MyDocs>
  <Member1>
   <summary>
     MyMethod is designed to
     demonstrate XML documentation
   </summary>
  </Member1>
  <Member2>
    Another member's documentation
  </Member2>
</MyDocs>

then we can pick out the XML comments for MyMethod using:

/// <include file='XMLFile1.xml' 
           path='/MyDocs/Member1/*'/>
public void MyMethod(int param1,
                       string param2)
{
}

To include the XML comments for other methods you would write another <include> tag at the appropriate place and change the path to pick out say /MyDocs/Member2/* and so on.

Using a brand new tag each time you need to document a new member doesn’t sit well with the overall philosophy of XML syntax and semantics but it works perfectly well.

A better method is to introduce a single tag for members and a name attribute to identify which member the tag applies to, for example:

<?xml version="1.0" encoding="utf-8" ?>
<MyDocs>
 <Member name="MyMethod" >
  <summary>
   MyMethod is designed to
   demonstrate XML documentation
  </summary>
 </Member>
 <Member name="AnotherMethod">
  Another member's documentation
 </Member>
</MyDocs>

Notice that now the member that the <Member> tag refers to is specified by the name attribute. 

Now the appropriate XML block can be picked out using a slightly more complicated XPATH specification:

/// <include file='XMLFile1.xml'
 path='/MyDocs/Member[@name="MyMethod"]/*'/>

This works in exactly the same way and generates exactly the same XML comments as before. You can use any identification method you like as long as you can write an XPATH statement to pick out the bit of the XML contained in the file that you need – however the use of a name attribute is a fairly standard way of organising things.

It is arguable that using <include> breaks the connection between the XML comments and the code. It is true that you are more likely to keep the documentation up-to-date if the comments are part of the code you are modifying rather than something you have to go in search of.

The conclusion has to be that you should only resort to <include> if there is a clear reason to do so.

Next we need to look at ways of processing the XML generated to create some good looking documentation.

If you would like to be informed about new articles on I Programmer you can either follow us on Twitter, on Facebook , on Digg or you can subscribe to our weekly newsletter.

<ASIN:0596007647>

<ASIN:1451531168>

<ASIN:067232797X>