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 tagApplies toDescriptionVerified
<c>AllUsed to delimit short code fragments in your documentation 
<code>AllSimilar to <c> except that it is used if one or more lines of code are to be marked 
<example>AllUsed to provide an example of how a method or member of your class can be used 
<exception>MethodUsed 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>AllUsed to create a (numbered or bulleted) list of items or a table 
<para>AllUsed inside other tags as a paragraph start – similar to the HTML <p> tag 
<param>MethodUsed 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>MethodUsed to show that a word is a method parameter – the documentation generator verifies that this parameter exist for this method✓
<permission>MemberUsed to indicate the accessibility of a member – the documentation generator verifies that the member specified by the cref attribute exists✓
<remarks>TypeUsed to describe a type – to describe a member of a type, use the <summary> tag instead 
<returns>MethodUsed to describe the return value of a method – similar to Javadoc's @return tag 
<see>AllUsed 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>AllUsed for generating an entry in the 'See also' section✓
<summary>MemberUsed to describe a member – to describe a type, use the <remarks> tag instead✓
<value>PropertyUsed 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 tagSyntax 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: 
<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: 
<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: 
<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: 
<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: 
<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: 
<summary>This method is called to return a random
 <c>int</c> between 1 and 10.</summary>

<value>Syntax: 
<value>description</value>

Example: 
<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.

..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset
3.147.47.166