Many of you have heard of JavaDoc, a feature of Java that automatically generates HTML documentation for your code. C#, and the C# compiler, is capable of a similar function, yet produces XML instead of directly producing HTML. This makes the documentation much more flexible.
Commenting Syntax
To use the XML commenting features of C#, you begin by commenting your source code using the special comment syntax, /// (three slashes). After the slashes you use one of the predefined tags for documentation comments, or embed your own. Your custom xml tags will carry over into the result XML documentation.
| Predefined Tag | Used for |
| <c> | a way to indicate that text within a description should be marked as code |
| <code> | a way to indicate multiple lines as code |
| <example> | lets you specify an example of how to use a method or other library member |
| <exception> | lets you document an exception class |
| <include> | lets you refer to comments in another file, using XPath syntax, that describe the types and members in your source code. |
| <list> | Used to insert a list into the documentation file |
| <para> | Used to insert a paragraph into the documentation file |
| <param> | Describes a parameter |
| <paramref> | gives you a way to indicate that a word is a parameter |
| <permission> | lets you document access permissions |
| <remarks> | where you can specify overview information about the type |
| <returns> | describe the return value of a method |
| <see> | lets you specify a link |
| <seealso> | lets you specify the text that you might want to appear in a See Also section |
| <summary> | used for a general description |
| <value> | lets you describe a property |
Example
The following example adds comments to our introductory HelloWorld console application.
using System;
namespace HelloWorld
{
publicclass HelloWorld
{
publicstaticint Main(string[]args)
{
System.Console.WriteLine("HelloWorld");
stringname= System.Console.ReadLine();
return(0);
}
}
}
To get the resulting XML Documentation file, we call the csc compiler with the /doc option.
csc /doc:HelloWorld.xml helloworld.cs 或修改工程的property.build.output.xmldocument.(在2005中)
HTML Web Pages
You may be asking yourself: how do I get nicely formatted web pages? Well, you could write your own XSL to transform the XML documentation file, or you could use
Visual Studio.NET. By using the Tools -> Build Comment Web Pages option, you can get a set of html files detailing your entire project or solution. Here is a screen shot by building web pages for our HelloWorld example:
