Professional.Open.Source.dot.NET.Development.Programming.with.NAnt.NUnit.NDoc [Electronic resources] نسخه متنی

Configuring the C# Compiler to Create the XML File

There are many different ways to tell various C# tools to create the XML documentation file. For Microsoft's .NET csc and Mono's mcs compiler, use the doc option of the compiler. Portable.NET isolates their parsing tool called csDoc (http://www.southern-storm.com.au/docs/pnettools_3l) that, similar to Javadoc, parses the source file for comments, constructing the XML documentation as output. Interestingly enough, Portable.NET has added a number of tags to their standard set of supported tags (<overload>, <devdoc>, <altcompliant cref="CREF"/>, <altmember cref="CREF"/>, <internalonly/>, <nodoc/>, <platnote platform="PLATFORM"> ... </platnote>, and <threadsafe> ... </threadsafe>). See the csDoc documentation for more details.

Invoking the parser validates the appropriate tags. Listing 5.17 is example source code documentation (from LogKit.Net see http://logkit-net.sourceforge.net) that uses raw HTML to further format the see major validated tag.

Listing 5.17. Example of C# Comments

/// <summary>
/// Class to write to an EventLog Target.
/// </summary>
/// <remarks>
/// <table><tr><td>Logging Priority  <see
cref="Priority"/></td><td>Event Log Entry  <see
cref="EventLogEntryType"/></td></tr><tr><td>DEBUG</td><td>Information</
td></tr><tr><td>INFO</td><td>Information</td></tr><tr><td>WARN</td><td>
Warning</td></tr><tr><td>ERROR</td><td>Error</td></tr><tr><td>FATAL_ERR
OR</td><td>Error</td></tr></table>
/// </remarks>
public class EventLogTarget : AbstractOutputTarget{
..... // Class contents left out.
}

Listing 5.17's C# XML documentation, when run through a C# compiler, results in the XML output in Listing 5.18.

Listing 5.18. XML Output from C# Comments

<?xml version="1.0"?>
<doc>
<assembly>
<name>LogKit.Net</name>
</assembly>
<members>
<member name="T:org.apache.log.EventLogTarget">
<summary>
Class to write to an EventLog Target.
</summary>
<remarks>
<table><tr><td>Logging Priority  <see
cref="T:org.apache.log.Priority"/></td><td>Event Log Entry  <see
cref="T:System.Diagnostics.EventLogEntryType"/></td></tr><tr><td>DEBUG<
/td><td>Information</td></tr><tr><td>INFO</td><td>Information</td></tr>
<tr><td>WARN</td><td>Warning</td></tr><tr><td>ERROR</td><td>Error</td><
/tr><tr><td>FATAL_ERROR</td><td>Error</td></tr></table>
</remarks>
</member>
... <!-- other members omitted />
</members>
</doc>

The documentation is now in a form that can be transformed into virtually any output desired. But before you run and get your XSLT book, take a look at some of the readily available tools from the Open Source community.