XML Documentation

   


The familiar commenting symbols // and /* */ allow you to insert comments in the source code to facilitate the reader's understanding of the code. Comments are read in conjunction with the source code. Apart from commenting your code, it is also important to document it. Program documents are, as opposed to source code comments, viewed separately and independently from the source code. A good example of program documentation is the .NET Frameworks class library documentation. Here you can find specific class and struct descriptions, along with descriptions of their members and examples of how to use them; but you won't find any of the underlying source code.

You could set out to write your program documentation as a completely separate document in an editor like Notepad. This is what programmers of older languages, such as C and Pascal, had to do. C# offers a better alternative, it allows you to insert special documentation comments in the code that are recognized by the compiler. Documentation comments can automatically be transformed into Extensible Markup Language (XML) files by giving suitable commands to the compiler. These XML files can then be transformed into viewable documents similar to those seen in the .NET Frameworks documentation. However, this latter transformation is not supported by the compiler and is beyond the scope of this book.

There are several advantages associated with this way of documenting your code:

  • You can automatically extract the documentation from the documentation comments in your code.

  • The compiler can validate some of the document details by comparing them with the actual code.

  • The compiler can automatically insert information into the documentation.

  • The compiler can enforce a standard documentation format.

  • XML is a powerful format in which to keep your documents.

A Simple Documentation Example

The following section is only meant to provide a brief introduction to XML documentation in C#.

The documentation comments can be applied to any class or struct or their members (methods, instance variables, and so on) and must be positioned just before one of these language element definitions. A documentation comment starts with three forward-slashes /// and consists of XML tags and descriptive text. The C# compiler recognizes a set of pre-defined XML tags, but you can also define your own tags.

A couple of commonly used pre-defined XML tags are <summary> and <remarks>. The <summary> tag is meant to contain a brief overview of the language element, whereas <remarks> can contain a longer description or special remarks.

Note

graphics/common.gif

At this time of writing, the C# compiler recognizes 16 pre-defined XML tags. It is beyond the scope of this book to describe these. However, you can find more information about them in the .NET Framework SDK Documentation if you search for "XML documentation and "tags for comments."


Listing 21.2 provides a simple example to illustrate the use of the <summary> and <remarks> tags. As you can see, a <summary> comment must commence with <summary> and end with </summary> to be well formed. The compiler will report an error if you divert from this standard XML syntax.

Listing 21.2 RacingCar.cs
01: using System; 02: 03: ///<summary>The Car class represents a car in the car game </summary> 04: ///<remarks>The car can be moved forward and backward</remarks> 05: class Car 06: { 07:      ///<summary> distance represents the amount 08:      ///of kilometers the car has driven </summary> 09:     private uint distance = 0; 10: 11:      ///<summary> Used to move the car forward and backward </summary> 12:      ///<remarks> To reverse the car you must pass a negative argument </remarks> 13:     public void Move(uint addDistance) 14:     { 15:         distance += addDistance; 16:         Console.WriteLine("Moving { 0}  kilometers", addDistance); 17:     } 18: } 19: 20: class Tester 21: { 22:     public static void Main() 23:     { 24:         Car myCar = new Car(); 25:         myCar.Move(100); 26:     } 27: } 

To generate a well-formed XML document from Listing 21.2, you need to provide the following command to the compiler:

 csc /doc: RacingCar.xml RacingCar.cs 

This will cause the compiler to generate a file called RacingCar.xml (you can view this file with Notepad) with the following contents:

 <?xml version="1.0"?> <doc>     <assembly>         <name>RacingCar</name>     </assembly>     <members>         <member name="T:Car">             <summary>The Car class represents a car in the car game </summary>             <remarks>The car can be moved forward and backward</remarks>         </member>         <member name="F:Car.distance">             <summary> distance represents the amount             of kilometers the car has driven </summary>         </member>         <member name="M:Car.Move(System.UInt32)">             <summary> Used to move the car forward and backward </summary> <remarks> To reverse the car you must pass a negative argument </remarks>         </member>     </members> </doc> 

Apart from the XML tags we provided and their associated text, the compiler has automatically added an <assembly> tag and a <member> tag for each member preceded by a documentation comment. Each <member> tag is associated with a name attribute, which commences with a capital letter. T stands for type, F for field, and M for method.


   


C# Primer Plus
C Primer Plus (5th Edition)
ISBN: 0672326965
EAN: 2147483647
Year: 2000
Pages: 286
Authors: Stephen Prata

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net