Use C# To Write Comments And Documentation

Attached is a C# program which demonstrate the ability of C# to produce documentation and comments from C# code .

Comments and Documentation are the most hated tasks by programmers. By using C#, programmers can automatically build the documentation and comments in the code. This documentation is a XML file which is more or less self explanatory.

The C# compiler checks the comments and generates the XML and generates errors if it finds any false tag or false references. This means there are some basic rules and standards to write the comments in C#. If you want to use this C# feature you need to follow these basic rules and standards. If you follow these standards, it might save you a lot of documentation time.

Let's get with the rules and syntax for commenting in C#. All this is given in the sample C# file called CFactorial.cs which computes the Factorial of any number [less than 20] and gives 0 for numbers greater than 25 or so. Why? Can any one guess? As with other languages it should give OVERFLOW error .. but here it is giving 0 ....(we will discuss this C# feature some time later).

The first rule for commenting is it should have /// three slash for comments as C# supports C++ style commenting so commenting can be done by // -- two slashes --  but for Documentation /// is necessary.
 
These documentation-specific comments can be broadly divided into
  • Describing an Element
  • Adding remarks and lists
  • Describing Parameters
  • Describing Methods/Properties
  • Providing Examples
  • Compiling the Code
We will go through each one by one.
 
Describing an Element

It can be done by using <summary> tag

  1. ///<summary> description of element </summary>  
You can add a paragraph to the description by using <para> tag.
 
Reference to other elements are added using <see> tag.
  1. ///<para> this uses private variable   
  2. ///<see cref="nFactorial"/>  
  3. ///</para>  
Beware of not giving a wrong reference;  C# compiler checks each and every reference and will give error if it finds a wrong reference.

Adding Remark and List

Remark is the place where you place the bulk of the documentations, which is done by <remarks> tag.This is in contrast with the summary where you should only provide a brief description.
 
You can use para and lists in the remarks section , which can be bulleted or numbered.

  1. ///<list type="bullet">  
  2. ///<item>Constructor:   
  3. ///<see cref="Factorial"/>  
  4. ///</item>  
  5. ///</list>  

Another tag that is useful is <paramref> which is used to reference and describe the parameter passed

  1. ///<remarks>  
  2. ///<paramref name="nFactorialToComp"/>in the private variable   
  3. ///<see cref="nFactorialToComp"/>  
  4. ///</remarks>  

Describing Parameters

For this purpose <param> tag is used (please see the C# code that is there with this article to understand)

  1. ///<param name="nFactorialToComp">  
  2. ///.........   
  3. ///</param>  
You can use <para> tag in between too. 

Properties

For properties you must use a special tag called <value> With this tag you can specifically flag a property , and the <value> tag more or less replaces <summary> tag.

Example

The <example> tag includes the example of your application.
 
It means you have to give a complete code that will be there with <code> tag that contains a real C# code as an example to show the uses,

  1. ///<example> this is how u use the code   
  2. ///<code>  
  3. ///public static void Main(string[] srgs)   
  4. ///.......   
  5. ///</code>  
  6. ///</example> 

Compling the Code

The switch that you have to use for xml documentation is /doc,
 
example
 
c:\>csc /doc:Factorial.xml /out:Factorial.exe Factorial.cs
 
After the XML file is generated you will see some constant that you never supplied appears there, they are the ID's that C# adds there for reference and to categorize Methods, Properties , Asemblies , etc., let's have a look at these IDs:
 
N----Namespace
T----Type,This can be Class, Interface, struct, enum, or delegates
F----fields of class
P---Property indexer or indexed property
M---Methods special methods constructor and operator(overloaded)
E----Events
!----error string (C# was unable to resolve some references)
 
This ends the comments for documentation.
 
Hope this article and example helps reduce the burden of documentation and gives you all a new habit of commenting your CODE. I will highly appreciate if you give me any feedback on this article and the example.
 
Good luck and Enjoy C#