C# supports
a
new
Documentation
Comment
style, with three
slash marks
(///
). You can see these comments sprinkled
throughout Example 13-3. The Visual Studio.NET editor
recognizes these comments and helps format them properly.
The C# compiler processes these comments into an
XML file. You can create this file by using the /doc command-line
switch. For example, you might compile the
program in Example 13-3 with this command line:
csc filecopier.cs /r:System.Windows.Forms.dll /r:mscorlib.dll
/r:system.dll /r:system.configuration.dll /r:system.data.dll
/r:system.diagnostics.dll /r:system.drawing.dll /r:microsoft.win32.interop.dll
/doc:XMLDoc.XML
You can accomplish this same operation in Visual Studio .NET by clicking a project icon in the Solution Explorer window, selecting View → Property Pages on the Visual Studio menu, and then clicking the Configuration Properties folder. Within the Configuration Properties folder, click the Build property page and type in a name for the XML Documentation File property to specify a name for the XML file you want to produce.
Either approach produces the file XMLDoc.XML with your comments in XML format. An excerpt of the file that will be produced for the FileCopier application of the previous section is shown in Example 13-4.
Example 13-4. The XML output (excerpt) for file copy
<?xml version="1.0"?> <doc> <assembly> <name>FileCopier</name> </assembly> <members> <member name="T:FileCopier.Form1"> <summary> Form demonstrating Windows Forms implementation </summary> </member> <member name="F:FileCopier.Form1.components"> <summary> Required designer variable. </summary> </member> <member name="F:FileCopier.Form1.tvwTargetDir"> <summary> Tree view of potential target directories </summary> </member> <member name="F:FileCopier.Form1.tvwSource"> <summary> Tree view of source directories includes check boxes for checking chosen files or directories </summary> </member> <member name="F:FileCopier.Form1.txtTargetDir">
The file is quite long, and although it can be read by humans, it is not especially useful in that format. You could, however, write an XSLT file to translate the XML into HTML, or you could read the XML document into a database of documentation.
One of the simplest things to do with the documentation comments in
your source code is to allow Visual Studio to generate a Code Comment
Web Report. You choose this from the Tools
menu
(Tools → Build Comment Web Pages...), and the IDE does the
rest. The result is a set of HTML files that you can view from within
the IDE or from a browser, as shown in Figure 13-9.
Every member preceded by a documentation comment is included in the
XML file via a <member>
tag added by the
compiler, along with a name attribute that identifies the member. You
can also make use of predefined tags to increase the richness of the
generated documentation. For example, you can add
<see>
comments to reference another member
in the class or <exception>
to document
exception classes. A detailed discussion of XML Documentation
Comments is beyond the scope of this book, but a complete listing of
available tags can be found in the C# Programmers
Reference that is included with
Visual Studio.
3.142.135.249