This chapter is from the book
This chapter is from the book
This chapter is from the book
Documentation
If source code is the heart of an application, documentation is its soul. Documentation is often neglected and not updated regularly. Especially when the schedule of a project is tight and there isn't much time left, people start to save the time they've lost by cutting the resources for writing documentation.
Mono and C# try to integrate documentation and code in order to minimize the work for a programmer. It's far easier to write documentation inside a program than with the help of an external editor. In addition, documentation that's inside the source is more consistent with the software itself than external texts.
C# relies on XML. Therefore, XML is used to document an application. The next example shows how XML can be used to document a simple application:
using System;
class MyLoop
{
public static void Main()
{
/// <summary>
/// This is a free advertisement
/// for http://www.postgresql.at
/// </summary>
Console.WriteLine("Check out http://www.postgresql.at");
/// <seealso> http://www.go-mono.org </seealso>
}
}
It's possible to embed XML in any C# application. A rich set of elements are defined, as shown in Table 3.2.
Table 3.2 XML Elements
|
XML Element |
Meaning |
|
<c> |
Marks a paragraph as code |
|
<code> |
Marks text as code |
|
<doc> |
Root element of the XML file |
|
<event> |
Describes an event |
|
<example> |
Marks an example |
|
<exception> |
Defines an exception that a function can provide |
|
<field> |
Describes a field |
|
<list> |
Defines a list or a table |
|
<method> |
Describes a method |
|
<para> |
Marks a text as paragraph |
|
<param> |
Defines a parameter of a method |
|
<paramref> |
Marks a word as parameter |
|
<permission> |
Defines user rights |
|
<property> |
Defines a property |
|
<remarks> |
Adds remarks and important messages |
|
<returns> |
Defines the return value of a method |
|
<see> |
Defines a link |
|
<seealso> |
Points to additional documentation |
|
<summary> |
Summary |
|
<type> |
Defines a type |
In this list, we omitted the corresponding closing tags because they're just as in HTML. For example, the closing tag for <tag> would be </tag>.
Let's see what happens when we execute the program:
[hs@duron mono]$ mono ex.exe Check out http://www.postgresql.at
At the time this text was written, there was no suitable tool for processing the documentation inside a program.