Introduction

Documentation has been always a neglected task in the software development life cycle. While developing applications, most of the software developing professionals including senior professionals tend to forget about documentation although everyone is aware about the difficulties that are faced during code maintenance application. Documentation is a very important aspect specially when developing large and very big applications involving a number of modules.

When developing an application with C#, we can minimize the effort of making and maintaining the application documentation. As a C# application developer, it is common to give inline comments, these inline comments can be the source to generate a strong and more accurate documentation. Inline comments are the most important part of any code as they provide valuable information about the part of the code that is written. And most importantly it is written when the system is constructed. One of the wonderful features of the C# compiler is that it supports automatic creation of documentation using comments written in the code, the only distinction being that the documentation is produced in XML. Unlike other automated documentation provided by various programming languages, that generates HTML based documentation, C# produces in XML but there are tools available that take XML files as the input and produce HTML based documentation. As the C# stores all the comments in an XML file, users have the flexibility to develop excellent documentation from C#. Code comments, user manuals, developer manuals, test plans, and many other documents can be generated from a single source using XML tags.

The process of generating an XML based documentation is done by adding comments to various parts of the code. The process can be described in the following manner:

In-depth of C# Documentation

Before we proceed in depth about the automated documentation part, let's see some of the important aspects that are required to be known when developing the XML based documentation. The main point is that the comments needs to start with "///" as this is the way in which the compiler identifies tags for XML based documentation. "//" way of comments are also supported in C# but in general, the compiler ignores anything that is put after this, but when the compiler encounters another "/" then this indicates that this is an XML comment and needs to be handled properly. Usually the three slashes are followed by the XML tag, this contains the property and value along with it as needed.For example:

/// <Summary>
/// this is a place where something is done
/// </Summary>

There are various predefined tags that are available for the purpose of generating the document. The developer has the freedom to use any type of XML tags to document the code, only thing is that these tags need to adhere to the XML syntax. The predefined tag indicates the type of documentary information that is being given, and the compiler validates these tags against certain aspects of these and produces the output. Other elements are used for the layout and/or formatting purpose. The C# compiler takes these comments embedded inside the XML tags and builds the XML based documentation. It generates errors when a false reference is encountered.

The following lists describe the main documentation elements provided and are available for usage. The important thing to remember is that each element should be written between its opening and closing tags, Also, some of the tags take some further mandatory attributes. For example, the 'cref' attribute can be used in any element, but it should be used only when it is advisable.

Tag

Description

<summary>

This tag is used to hold the overview information of any documenting element.

<remarks>

This helps to expand the comments that are given in the summary and usually follows it.

<param name="name">

Describes a parameter passed to a method. The compiler checks that the 'name' value matches an actual parameter in the code. Also, if you give documentation for one parameter value, the compiler will expect you to give documentation for them all.

<paramref name="name">

Identifies the mention of a parameter name within some other descriptive element, for instance within 'summary' tags. The idea is that this mentioned name can be styled differently from the surrounding text. The compiler checks that the 'name' value matches an actual parameter in the code.

<param name="name">

Describes a parameter passed to a method. The compiler checks that the 'name' value matches an actual parameter in the code. Also, if you give documentation for one parameter value, the compiler will expect you to give documentation for them all.

<returns>

Describes the return value for a method. As the descriptive field is just free text there is no compiler checking.

<exceptions cref="type">

Describes an exception that may be thrown by a method. The 'cref' attribute refers to a type or field (such as System.Exception), and the compiler checks that this reference is available from the current compilation environment.

<permission cref="type">

Describes a permission requirement for a type or member. The cref attribute refers to a type or field (such as System.Security.PermissionSet), and the compiler checks that this reference is available from the current compilation environment.

<value>

Describes a class property.

<example>

Gives an example of the use of the referenced object (for example a class method). The 'example' element is often used with the following two elements.

<c>

Marks up a single phrase or line as a code example. Generally used in conjunction with the 'example' element.

<code>

Marks up multiple lines as code examples. Generally used in conjunction with the 'example' element.

<see cref ="type">

Used to identify a crossreference in the documentation; designed to be used inline within a description element. The cref attribute refers to a type or field, and the compiler checks that this reference is available from the current compilation environment. and the see also tag is used in a separate section. This allows the documentation to create crossreferences.

<seealso cref ="type">

Used to identify a crossreference in the documentation; different from 'see' in that it is designed to stand alone. The cref attribute refers to a type or field, and the compiler checks that this reference is available from the current compilation environment.

Some of the formatting tags are as follows:

Tag

Description

<para>

Used within descriptive tags like 'remarks', 'summary', etc. to wrap a single paragraph.

<list type = "bullet" | "number" | "table">

"Top level tags for a list, where this may be one of the three types shown.There are more elements associated with the list tag: the following code gives an example of these.

C# Documentation Example

Let's take an example and then try to use the above information to get an automated documentation file.

The above is a typical example of an application during the construction phase and then we struggle at the time of maintenance as to what the function or the class was supposed to do! Let's give some comments and do the needful.

using System;
using System.Data;
namespace ExampleDocumentation
{
///<summary>/// DocumentationClass: Is the class that will be used for explaining the
/// example of automated documentation
///</summary>publicclass DocumentationClass
{
///<summary>/// public DocumentationClass () :
/// Is the constructor used for DocumentationClass class
///</summary>public DocumentationClass ()
{
}
///<summary>/// public void DocumentationClassMethod: Is a void method
/// that does not return anything and takes no parameters.
/// It does the functionality of some addition and subtraction to
/// get the result
///</summary>publicvoid DocumentationClassMethod ()
{
}
}
}

As you can see above, now we have added some valuable comments that tend to have lots of value. Now to generate the documentation we can have the following command

<Directory>\Microsoft.NET\Framework\v1.1.4322>

In the above, command /doc instructs the compiler to produce the documentation named doc.xml. And this will produce the following output:

<?xmlversion="1.0"?><doc><assembly><name> DocumentationClass</name></assembly><members><membername="T:ExampleDocumentation.DocumentationClass"><summary>
DocumentationClass: Is the class that will be used
for explaining the example of automated documentation
</summary></member><membername="M:ExampleDocumentation.DocumentationClass.#ctor"><summary>
public DocumentationClass () :
Is the constructor used for DocumentationClass class
</summary></member><membername=
"M:ExampleDocumentation.DocumentationClass.DocumentationClassMethod"><summary>
public void DocumentationClassMethod:
Is a void method that does not return anything
/// and takes no parameters.
///It does the functionality of some addition and substation to
get the result
</summary></member></members></doc>

Some points

Some of the constants are attached usually with the commented object, these are the ID's that are used to identify the type code and part. Usually these are categorised in the following manner:

M denotes the Methods special methods constructor and operator(overloaded)

E denotes Events

! denotes an error string that C# was unable to resolve some references

Generation of C# documentation with Visual Studio NET 2000 IDE

The documentation can be generated in the following way from the Visual Studio NET 2000 IDE:

Open the property page for the project, usually by right-clicking on the project in the Solution Explorer, and click Properties.

Click the Configuration Properties folder.

Click the Build option.

In the right pane, there will be a property field called XML Documentation File. Enter the required information like the path and name of the file.

Generating HTML based Documentation with Visual Studio .NET

The XML based on the C# compiler can be used to generate the HTML based documentation. Visual Studio takes the doc.xml file generated by the C# compiler and produces whole documentation of HTML pages. To do this we need to follow the same process and then go to the Tools menu in Visual Studio .NET and select Build Comment Web Pages, there will be a dialog box that will appear. In this, select the projects to create the documentation. There is also the possibility to choose the specific part of the solution to generate the documentation.

Problems with the C# Documenter

The automated documentation in C# has some flaws; following are some of them that need to be taken into consideration:

If in any case if you have forgotten to mention any comments for any method, it will just be ignored

Even if the comments are written and you have written "//" instead of "///" then again the documentation will not have any reference of these comments

While generating C# documentation whenever there is any kind of return type explicitly this has to be specified

License

This article has no explicit license attached to it but may contain usage terms in the article text or the download files themselves. If in doubt please contact the author via the discussion board below.

Share

About the Author

Professionally I am a Software Engineer. Have over 6 years of experience and specialize in Microsoft Tech. I have done most of my project in VB, ASP, ASP.NET (1.1 and 2.0), C# (1.1 and 2.0) with back end support of MS-Access, Oracle, MS - SQL server etc. Also worked as the DBA for MS SQL Server (2000, 2005 and 2008).

I have stamp of Brain Bench and Microsoft certified professional to enhance my skill set.

For any query, reach me at jaiprakash.bankoll@gmail.com. Will be very happy to respond back.

** Disclosure - I work for Innovasys - the company that produces the product mentioned below **

Just wanted to mention our commercial product for producing documentation from Xml source comments - Document! X for .NET documentation. As well as the core .NET documentation functionality (including Visual Studio 2012 support and mobile/tablet output) it includes a Visual Comment Editor integrated with Visual Studio (edit C# xml comments in a WYSIWYG editor) as well as a full external authoring environment for both reference and conceptual topic content.

Document! X has a good pedigree; it has been available since before the .NET 1.0 release, supports database and XSD documentation too, and is used by many of the commercial .NET component companies including Infragistics, Dundas, Xceed, GrapeCity, Telerik etc.

I'm an experienced programmer, so I do know how important documentation is, but I still say that the MS system is just far too much hassle. How often do we come across code that has used it? I can't really say that I ever have, unless it is MS themselves who no doubt have departments whose only function is to whip programmers until they comment.

I do comment, the usual way most programmers comment, i.e in the way that they have built themselves over the years. We probably each have our own little apps to extract from our own system. Not saying here our own methods are better than MS's, but I will say they are probably not worse.

Then maybe -/* * [Func] public List<FileInfo> FindFiles(RegEx regie); * [Comment]Something about the function */(No need to comment the function params or return types, because my scanner looks for itself)

The point is that there is a bare minimum of commenting, but get workable results.

But still, I tried to be a good boy, using a copy of a faily large project, that had many sub projects, I scanned through changing my comment system to the MS C# comment system.

The first thing you discover is that XML is definately not a great platform for documenting C#.

Every use of a built in collection is in XML a tag. Dictionary<long, FileInfo> or List<string>. This makes no difference whether it is my little comment changer that does it or typed manually, the fact remains that within your ///<Summary</Summary> you have to deter from the easy type and go when ever you need to mention a collection.

So personally I will be stearing clear of the MS C# documenting method. As it happens I had a moan to a fellow programmer online last nigt and the first thing he said (before I had my full and well deserved moan) 'Oh that cr*p, its too much hassle'. Stole my thunder the so and so

I had to sign up, I felt a bit guilty borrowing code ideas and not giving anything back.

Though I sort of agree with you about MS commenting hassle, but see it as an option for programmers/developer. This option could be used anytime and i have a strong feeling that MS is certainly looking at various other option to minimize the effort of maintaining comments and code base .

Hi... I'm using Visual Studio 2005.I want to create the HTML version of the documentation.As I read from your article, I must choose the "Build Comment Web Pages" from "Tools" menu. However, in my Tools menu..there is no "Build Comment Web Pages" option.So how can I create the html doc???

One thing that you can do is:1> Go to project properties2> Select the build tab3> Set the documentation path to either bin or to the specific folder4> Download automated tool that takes xml and generates either chm or html help files

As I just started to learn how to produce auto generated ducumentation in C#, I have gone thru many trials + errors to see the target HTML documentation file with this tutorial. With the default IE 6 setting, there is no way to make the HTML output come alive. I found one solution related with that problem, but that is not enough to see the real outputs the author must have intended to with this article.

When the project link in the initial HTML page does not open the target page. It opens just a blank page with Restricted sites warning. I made the target output open by clicking Enable for the IFrame option in Security >> Custom. But it just opens next page. It does not link to the following pages.

When I do the same thing using Firefox, it works fine.

Doesn't this article have to include the direction to open it properly with IE as with Firefox?

but I cant seem to find how to add comment to enum value member. When I compile the class library with "/doc" and the XML comment file, the enum members get green underline and on mouse over I get this error message: