C# Tutorial Lesson 19: Code Documentation

The C# compiler supports the automatic creation of class documentation. Where the equivalent functionality for Java produces HTML, the C# documenter produces XML. This means that the C# documentation is not as immediately ready to use as the Java documentation. However, it does allow there to be different applications which can import and use the C# documentation in different ways. (Note: using Visual Studio you can also create HTML documentation, but we will not be covering this here).

Sadly, Microsoft did not bundle a basic documentation reader with C#.. Even worse, however, the documentation automatically produced by C# is rather less extensive than that produced by Java's javadoc tool. Indeed, as we note in the final section of this lesson, this XML documentation is so lacking that we have been driven to write an alternative documenter.

C# Documentation Comments

To document any element in a C# script, you precede the element with XML elements. Each of the lines comprising this documentary code should be marked off as comments using the following special comment indicator (you can compare this with the standard comment indicators in Lesson 3)

///

The following code gives an example of how one can provide overview information about a class.

1.

/// <summary>

2.

/// The myClass class represents an arbitrary class

3.

/// </summary>

4.

public class myClass


You are at liberty to use any XML tags you wish to document the code - as long as they follow the XML syntax then the compiler will happily write them into the documentation. But Microsoft does provide a list of recommended XML elements for you to use. Some of these elements indicate the type of documentary information that is being given, and the compiler will validate certain aspects of these. Other elements are just used to give layout or formating information.

The following lists describe the main documentation elements provided. Note that the content of each element should be written between its opening and closing tags, and some of the tags also take further attributes. In particular, the 'cref' attribute can supposedly be used in any element, but we have just used it in the cases where it seems particularly appropriate.

Tag(s) Description
<summary> - holds overview information about any documentable element.
<remarks> - allows for expanded comments about any documentable element, following summary information.

Note: we still aren't sure if the descriptions of the tags above are correct. The following points describe the problem.

In favour of using the 'summary' and 'remarks' in the suggested way is the fact that Gunnarson, who helped create C#, sets things out in this way. It also correlates with the default behaviour of Visual Studio.NET, where 'summary' tags are given by default whenever you start documenting any element.

On the other hand, in the help files of the (production) version of .NET - v. 1.0.3705 - it explicitly states that the use of 'summary' is to hold overview information about a class member, whereas the use of 'remarks' is to hold overview information about a class. However, some of the examples given throughout these same help files conflicts with this advice - for example, in the description of the 'paramref' element, a class method is documented only with 'remarks'. Unfortunately, of course, this example also conflicts with what we say, since the example contains no 'summary' tag.

Basically, it's all been knocked together by a committee of rather befuddled monkeys. But the way we suggest is as good as any.

Tag(s) Description
<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.
<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 conjuction with the 'example' element.
<code> - marks up multiple lines as code examples. Generally used in conjuction with the 'example' element.
<see cref ="type"> - used to identify a cross-reference 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 cross-references.
<seealso cref ="type"> - used to identify a cross-reference 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.

The following elements are just used to provide layout information:

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

<list type="table">
<listheader>
<term>Animal</term>
<description>Type</description>
</listheader>
<item>
<term>monkey</term>
<description>hairy</description>
</item>
<item>
<term>pig</term>
<description>bald</description>
</item>
</list>

Note - in relation to the example of the 'list' tag given above - that the v. 1.0.3705 help documentation for the enclosed 'item' tag talks about a 'text' element in place of the second 'description'. But this seems to be just wrong.

Generating C# Documentation

You tell the compiler to produce documentation when compiling by invoking it with the switch:

/doc:file

In this switch, file represents the name of the file that you want the documentation written to. As the documentation is generated in xml format, the file should have the extension .xml. So, for instance, to produce the documentation for a program in sys.cs file in a file named my.xml, we would use the command:

csc sys.cs /doc:my.xml

Those working with Visual Studio .NET should set the 'XML Documentation File' property in the 'Build' directory of the project's Configuration Properties.

Problems with the C# Documenter

The C# documenter is lacking in many different areas. Here are just a couple of problems that make the documenter hard to live with.

Firstly, if you don't document a method, the documenter just ignores it (or else throws a warning). This forces you to document all methods, no matter how simple and obvious they might be, which is annoying when the computer could easily do it for you.

Secondly, while the compiler checks the parameter types of methods, even to the extent of providing the fully qualified parameter name, it fails to do this with the return values of methods. The user has to manually insert the return type, even though the compiler could easily produce this.

Link Building Information