Appendix D. XML documentation

Java simplified code documentation by introducing the special /** */ Javadoc comments and providing the javadoc.exe tool. C# also provides a mechanism for developers to document their code using a special comment syntax.

There are two ways to insert document comments in C# codes “ the second syntax should be familiar to Java developers: ^[1]

^[1] Unfortunately, if you are using csc.exe as the documentation generator, the delimited document comments are not recognized by it. Use the single line document comment instead.

• single line document comment /// doc comments here

• delimited document comment /** doc comments here */

While Javadoc parses the document comments to form HTML files, C#'s documentation generator creates an XML file. You can view the generated XML document with any XML file reader (Microsoft Internet Explorer is quite rudimentary but useable).

In C#, your XML comments must be well- formed . ^[2] While javadoc.exe tolerates non-well-formed HTML tags, the C# documentation generator will complain when it encounters non-well-formed documentation comments in your source codes.

^[2] Well-formed XML documents must obey basic XML constraints. If a document is not well-formed, it is not an XML document. Basic XML constraints include rules such as only one root element, elements properly nested, attribute values quoted, every start tag with a corresponding end tag, and case sensitivity.

In the spirit of XML, developers are free to invent and define their own documentation tags for their own project team. The C# Language Specification lists a set of recommended documentation tags, which is shown in Table D.1. ^[3]

^[3] I would suggest sticking closely to the recommended tags. You can invent your own in the unlikely event that the recommended tags do not meet your requirements.

The 'verified' column in the table shows if the tag is verified by the documentation generator. For verified tags, any verification problem (for example, you specified an exception type which cannot be resolved, or a method parameter that does not exist) will be shown as warnings or errors by the documentation generator.

Table D.1. Description of recommended documentation tags

Recommended tag	Applies to	Description	Verified
<c>	All	Used to delimit short code fragments in your documentation
<code>	All	Similar to <c> except that it is used if one or more lines of code are to be marked
<example>	All	Used to provide an example of how a method or member of your class can be used
<exception>	Method	Used to list an exception a method can throw (use the cref attribute of this tag to specify the exception type that will be thrown by this method) “ one method can have multiple <exception> tags
<list>	All	Used to create a (numbered or bulleted) list of items or a table
<para>	All	Used inside other tags as a paragraph start “ similar to the HTML <p> tag
<param>	Method	Used for describing a method's parameter; use this tag for methods , constructors and destructors. Similar to Javadoc's @param tag “ you can have multiple <param> tags for each method, one for each parameter
<paramref>	Method	Used to show that a word is a method parameter “ the documentation generator verifies that this parameter exist for this method
<permission>	Member	Used to indicate the accessibility of a member “ the documentation generator verifies that the member specified by the cref attribute exists
<remarks>	Type	Used to describe a type “ to describe a member of a type, use the <summary> tag instead
<returns>	Method	Used to describe the return value of a method “ similar to Javadoc's @return tag
<see>	All	Used for specifying a link (cross reference) in your comments to another member “ use the cref attribute to indicate the name of the member you want to link to; similar to Javadoc's @see tag
< seealso >	All	Used for generating an entry in the 'See also' section
<summary>	Member	Used to describe a member “ to describe a type, use the <remarks> tag instead
<value>	Property	Used to describe a C# property

Table D.2 gives the syntax of each recommended tag.

Table D.2. XML syntax of recommended documentation tags

Recommended tag	Syntax and example
<c>	Syntax: <c>text to be set like code</c> Example: Use the static methods in the <c>Utility</c> class if necessary.
<code>	Syntax: <code>source code or program output</code> Example: This is the way to use this method: <code> MyClass m = new MyClass(); m.DoThis(); </code>
<example>	Syntax: <example>description</example> Example: [View full width] <example>The following shows an example of how to use this method: <code> MyClass m = new MyClass(); m.DoThis(); </code> </example>
<exception>	Verification: The documentation generator will verify if this exception exists. Syntax: <exception cref ="name of exception">description of when this exception will be thrown</exception> Example: <exception cref= "FileNotFoundException"> If indicated file cannot be found. </exception>
<list>	Syntax: <list type="bullet""number""table"> <listheader> <term>term</term> <description>description</description> </listheader> <item> <term>term</term> <description>description</description> </item> ... <item> <term>term</term> <description>description</description> </item> </list> Example (a numbered list without a header): <list type="number"> <item> <description>Point 1</description> </item> <item> <description>Point 2</description> </item> <item> <description>Point 3</description> </item> </list>
<para>	Syntax: <para>contents</para> Example: [View full width] <example>There are two scenarios whereby this method can be used: <para>When an instance of this class is shared by more than one thread concurrently running.</para> <para>When there seems to be synchronization problems.</para> </example>
<param>	Syntax: <param name="name">description</param> Example: <param name="currPwd">Current password</param> <param name="newPwd">New password</param>
<paramref>	Verification: The documentation generator verifies that this parameter exists for this method. Syntax: <paramref name="name"/> Example: [View full width] <summary> Pass into <paramref="currPwd"/> the user's current password. </summary> <param name="currPwd">Current password</param>
<permission>	Verification: The documentation generator verifies that the member specified by the cref attribute exists. Syntax: <permission cref="member">description <permission>
<remarks>	Syntax: <remarks>description</remarks> Example: [View full width] <remarks>The <c>Vehicle</c> interface contains the abstract methods that must be implemented by any <c>Car</c> class.</remarks>
<returns>	Syntax: <returns>description</returns> Example: [View full width] <returns>A <c>float</c> value indicating the calculation results.</returns>
<see>	Verification: The document generator verifies that the member specified in the cref attribute exists. Syntax: <see cref="member"/> Example ( DoThat is another method in the same class): <see cref="DoThat"/>
<seealso>	Verification: The document generator verifies that the member specified in the cref attribute exists. Syntax: <seealso cref="member"/> Example ( DoThat is another method in the same class): <seealso cref ="DoThat"/>
<summary>	Syntax: <summary>description</summary> Example: [View full width] <summary>This method is called to return a random <c>int</c> between 1 and 10.</summary>
<value>	Syntax: <value>description</value> Example: [View full width] <value>Represents the number of objects this collection currently contains.</value>

A full example is shown below. It shows a Car class containing a single constructor, two private fields called maxSpeed and currSpeed (for maximum and current speeds respectively) accessible via two public properties, MaxSpeed and CurrSpeed . Car contains two public methods “ Accelerate and Decelerate “ which alter currSpeed 's value.

 1: using System;   2:   3: ///  <summary>  4: ///   This class is usually subclassed to more specialized   5: ///   car types. Known subclasses include  <c>  Toyota  </c>  and   6: ///  <c>  Nissan  </c>  .   7: ///  </summary>  8:   9: class Car{  10:  11:   private int maxSpeed;  12:   private int currSpeed;  13:  14:   public Car (int maxSpeed){  15:     this.maxSpeed = maxSpeed;  16:   }  17:  18:   ///  <remarks>  19:   ///    Invoke this method to increase the current speed  20:   ///    by a  <paramref name  =  "  factor  "/>  . The current speed  21:   ///    will never go beyond the car's maximum speed. So,  22:   ///    if this method is invoked when the sum of  23:   ///  <paramref name  =  "  factor  "/>  and the current speed is  24:   ///    greater than the maximum speed, the current speed will  25:   ///    be set to the maximum speed only.  26:   ///  </remarks>  27:   ///  28:   ///  <param>  29:   ///  <c>  factor  </c>  30:   ///    Factor you want to increase the current speed by  31:   ///  </param>  32:   ///  33:   ///  <see cref  =  "  Decelerate  ">  34:   ///    Use  <c>  Decelerate  </c>  to decrease the current  35:   ///    speed by a factor.  36:   ///  </see>  37:   ///  38:   ///  <returns>  39:   ///    An  <c>  int  </c>  which is the current speed.  40:   ///  </returns>  41:  42:   public int Accelerate(int factor){  43:     CurrSpeed += factor;  44:     if (currSpeed>maxSpeed)  45:       currSpeed = maxSpeed;  46:     return CurrSpeed;  47:   }  48:  49:   ///  <remarks>  50:   ///    Invoke this method to decrease the current speed  51:   ///    by a  <paramref name  =  "  factor  "/>  . The current speed  52:   ///    will never go below zero. If this method is invoked  53:   ///    with the difference between the current speed and  54:   ///  <paramref name  =  "  factor  "/>  less than zero, a  55:   ///  <c>  InvalidSpeedAssignmentException  </c>  will be  56:   ///    thrown.  57:   ///  </remarks>  58:   ///  59:   ///  <param>  60:   ///  <c>  factor  </c>  61:   ///    Factor you want to decrease the current speed by.  62:   ///  </param>  63:   ///  64:   ///  <exception cref  =  "  InvalidSpeedAssignmentException  ">  65:   ///    This exception is thrown if an attempt is made to  66:   ///    decrease the current speed to a negative value.  67:   ///  </exception>  68:   ///  69:   ///  <see cref  =  "  Accelerate  ">  70:   ///    Use  <c>  Accelerate  </c>  to increase the current  71:   ///    speed by a factor.  72:   ///  </see>  73:   ///  74:   ///  <returns>  75:   ///    An  <c>  int  </c>  which is the current speed.  76:   ///  </returns>  77:  78:   public int Decelerate(int factor){  79:     currSpeed -= factor;  80:     if (currSpeed<0)  81:       throw new InvalidSpeedAssignmentException();  82:     return currSpeed;  83:   }  84:  85:   ///  <value>  86:   ///   The maximum speed of this car.  <c>  MaxSpeed  </c>  is a  87:   ///   get-only property.  88:   ///  </value>  89:  90:   public int MaxSpeed{  91:     get {  92:       return maxSpeed;  93:     }  94:   }  95:  96:   ///  <remarks>  97:   ///  <c>  CurrSpeed  </c>  cannot be higher than  98:   ///  <c>  MaxSpeed  </c>  . If you set  <c>  CurrSpeed  </c>  to a  99:   ///   value higher than <c>MaxSpeed  </c>  ,  <c>  CurrSpeed  </c>  100:   ///   will be automatically set to  <c>  MaxSpeed  </c>  . 101:   ///  </remarks>  102:   /// 103:   ///  <value>  104:   ///   The current speed of this car.  <c>  CurrSpeed  </c>  105:   ///   is a get-set property. 106:   ///  </value>  107: 108:   public int CurrSpeed{ 109:     get { 110:       return currSpeed; 111:     } 112:     set { 113:       if (value>maxSpeed) 114:         currSpeed = maxSpeed; 115:       else 116:         currSpeed = value; 117:     } 118:   } 119: } 120: 121: class InvalidSpeedAssignmentException 122:       :ApplicationException{ 123: } 

If you are using csc.exe , it comes with a fully fledged documentation generator. Use the /doc option to generate the XML documentation of a source file:

 c:\expt>csc  /doc:TestClass.xml  TestClass.cs 

In this case, because my class does not contain a Main method, and is meant to be compiled into a DLL assembly, I compiled using the /target:library option too:

 c:\expt>csc /doc:TestClass.xml /t:library TestClass.cs 

On successful compilation, I get TestClass.dll and TestClass.xml .

Part of the XML document generated from the above source file is shown in an Internet Explorer window in Figure D.1

Figure D.1. Showing a high-level view of the XML documentation generated.

Notice that additional tags such as <assembly> have been inserted for you. Each member name attribute is given a value prefixed by a letter “ T is for type, M for method, P for property, F for field, E for event, and N for namespace.

Let's 'expand' out the Decelerate method. This is shown in Figure D.2.

Figure D.2. XML documentation generated.

Other tools are needed to convert the XML documentation file into something more presentation friendly. If you are using VS .NET then under the Tools menu select Build Comment Web Pages , and the corresponding HTML pages will be created for you. csc.exe cannot do that for you.