Open Source .NET Development [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

/// <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

<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.