C# Tutorial Lesson 19: Code Documentation
printer friendly version
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.
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.
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.
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.
There is a solution, however...
Driven by documentation frustration, the Softsteel team (well, Andy really, but we all
chipped in with biscuits), has produced a command-line documenter, written in C#. It’s
quite rusty at the moment, but is already a whole load better than the inbuilt
documenter. We’re working on improvements, but we’re releasing it as free software under
the GNU GPL in order to encourage community support.
The downloads for the documentation tool are now being handled by the download page
http://www.softsteel.co.uk/tutorials/cSharp/download.asp
|
