Configuring the C# Compiler to Create the XML FileThere 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. |