Attached is a C# program which demonstrate the ability of C# to produce documentation and comments from C# code .
Comments and Documentation is one of the most hated tasks by programmers. By using C# programmers can automatically builds 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 rule and standard to write the comments in C# If you want to use this C# feature you must need to follow these basic rules and standards. If you follow these standards, it might save your lot of documentation time.
Lets get with the rules and syntax for commenting in C#(all this is given in the sample C# file called CFactorial.cs which computes 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 comment is it should have /// three slash for comments as C# supports C++ style commenting so commenting can be done by // two slash too, 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 one by one.
1. Describing an Element
It can be done by using <summary> tag
///<summary>
description of element </summary>
you can add paragraph to the description by using <para> tag
Reference to other element are added using <see> tag
///<para> this uses private variable
///<see cref="nFactorial"/>
///</para>
beware of not giving wrong reference C# compiler check each and every reference and will give error if it finds a wrong references.
2. Adding Remark and List
Remark is the place where u place bulk of the documentations
is is done by <remarks> tag.This is in contrast with the summary where you should
only provide a brif description.
You can use para and lists in the remarks section , which can be bulleted or numbered
///<list type="bullet">
/// <item>Constructor:
/// <see cref="Factorial"/>
/// </item>
///</list>
Another tag that
is use full is <paramref> that are use to reference and describe the parameter passed
///<remarks>
/// <paramref name="nFactorialToComp"/>in the private variable
///<see cref="nFactorialToComp"/>
///</remarks>
For this purpose <param> tag is used
(please see the C# code that is there with this article to understand)
///<param name="nFactorialToComp">
///.........
///</param>
You can use <para> tag in between too.
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 replace <summary> tag.
The <example> tag include 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 example to show the uses
///<example>
this is how u use the code
///<code>
///public static void Main(string[] srgs)
///.......
///</code>
///</example>
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# add there for reference and
to catagerize like Methods, Properties , Asemblies and all , let have a look at
this 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 end the comments for Documentation.
Hope this article and example helps and reduce the burden of documentation and gives you all a new habit of commenting your CODE. I will be highly appreciate if you give me any feedback on this article and the example.
Good luck and Enjoy C#