Post
Ask Question

Use C# To Write Comments And Documentation

Introduction

Attached is a C# program that demonstrates 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 an XML file which is more or less self-explanatory.

The C# compiler checks the comments, generates the XML, and generates errors if it finds any false tags or false references. This means there are some basic rules and standards for writing 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.

What is commenting in C#?

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 anyone guess? As with other languages, it should give an OVERFLOW error, but here it is giving 0(we will discuss this C# feature sometime later).

The first rule for commenting is it should have /// three slashes 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 the <summary> tag.

/// <summary>
/// Description of the element.
/// </summary>

You can add a paragraph to the description by using the <para> tag.

Reference to other elements is added using the tag

/// <para>
/// This uses private variable
/// <see cref="nFactorial"/>
/// </para>

Beware of not giving a wrong reference. The C# compiler checks each and every reference and will give an error if it finds a wrong reference.

Adding Remark and List in C#

Remark is the place where you place the bulk of the documentation, 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.

/// <list type="bullet">
/// <item>
/// Constructor:
/// <see cref="Factorial"/>
/// </item>
/// </list>

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

/// <remarks>
/// <paramref name="nFactorialToComp"/> in the private variable
/// <see cref="nFactorialToComp"/>
/// </remarks>

Describing Parameters in C#

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.

Properties in C#

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 the <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.

/// <example>
/// This is how you use the code
/// <code>
/// public static void Main(string[] args)
/// {
///     // .......
/// }
/// </code>
/// </example>

Compilation of code in C#

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 constants that you never supplied appear there. They are the IDs that C# adds there for reference and to categorize Methods, Properties, Assemblies, 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 a 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).

summary

Hope this article and example help reduce the burden of documentation and give you all a new habit of commenting on your CODE. I would highly appreciate it if you give me any feedback on this article and the example.


Similar Articles