Dwell.Net CodeDoc
User Guide

This section describes how to use Dwell.Net CodeDoc to create documentation and formatted source code for your C# class libraries.

The Basic Steps

These are the basic steps required to create a documentation with the help of CodeDoc:

  1. Add XML comments to your C# source code (example). Note that CodeDoc does not require that you use the /doc option in Visual Studio—CodeDoc reads the C# source files directly.
  2. Optionally, write additional documentation topics in HTML (example, with HTML source, opens in a new window), or any document type that can display in a browser (e.g. Microsoft® Word). You can use CodeDoc's CSS styles (defined in "_CodeDoc.css"), or your own.
  3. Create a CodeDoc XML project file (example) that describes the structure of your documentation (e.g. table of contents and index entries) and which contains other information CodeDoc needs to generate your documentation set.
  4. Run the CodeDoc.exe console application. This will:
    1. Parse the XML comments from your C# source files (example) and generate one documentation topic for each C# XML comment (example).
    2. Optionally, if you want to publish your source code, C# will process your C# source files again, this time generating one formatted source code HTML file for each source file. In this case, your XML comments become embedded "documentation topics" (example, with HTML source, opens in a new window).
    3. Create a "DocBrowser" (DHTML-based documentation browser/viewer) for your documentation (example, opens in a new window). DocBrowsers include a table of contents and an index. DocBrowsers can be viewed either online (on a Web site) or offline (on a hard disk)—though in the latter case you need to pay attention to the "Mark of the Web" informaton in the CodeDoc project file documentation.

The following sections explain these steps in detail.

Adding XML Comments To Your C# Source Code

CodeDoc parses C# source files and looks for XML comments. (Click here for a list of C# constructs that can include XML comments.) This is a key difference between CodeDoc and Microsoft Visual Studio's processing of XML source files: CodeDoc ignores constructs (classes, methods, etc.) that don't have an XML comment.

The following is an example of a method documented using markup elements supported by CodeDoc.

C# 
/// <summary>
/// Changes the thermostat settings.  (Sample code.)
/// </summary>
///
/// <param name="desiredTemperature">The desired temperature in Fahrenheit degrees.</param>
///
/// <param name="airConditioning"><n>true</n> to turn on air conditioning, <n>false</n> to
/// 	turn it off.</param>
///
/// <returns>
/// <n>true</n> if the new settings are different than the previous settings.
/// </returns>
///
/// <remarks>
/// If <pr>airConditioning</pr> is set to <n>true</n>, the air conditioning system will
/// only run when the room temperature rises above <pr>desiredTemperature</pr>.
/// </remarks>
///
/// <example>
/// This example sets the thermostat to 72 degrees Fahrenheit.  The current temperature
/// is checked using the <r>CurrentTemperature</r> property; if it's is above 72, air
/// conditioning is turned on.
/// <code>
/// ThermostatSample thermostat = new ThermostatSample("1.2.3.4");
/// if (thermostat.CurrentTemperature > 72)
///     thermostat.SetThermostat(72, true);
/// else
///     thermostat.SetThermostat(72, false);
/// </code>
/// </example>
///
/// <seealso cref="Home.ClimateControl.ThermostatSample" />
/// <seealso cref="CurrentTemperature" />
///
public bool SetThermostat(double desiredTemperature, bool airConditioning)
{
	// real code goes here
	return true;
}

Click here to see the HTML documentation topic, generated by CodeDoc, corresponding to the example above.

The example above contains the following outer elements—XML elements which must appear at the outer level, not nested within other elements:

The example above also contains the following inner elements—XML elements which appear inside outer elements:

For more information on these XML markup elements, click the links above, or see CodeDoc XML Markup Reference for full information about all supported XML markup elements. In particular, here are a few XML markup elements not demonstrated by the example above:

Writing Additional Documentation Topics

CodeDoc automatically generates one documentation topic (an HTML file) for each C# comment in the documentation set (in typical usage). However, you may have information to convey to the readers of your documentation that doesn't fit the mold of XML comments. Examples:

In these cases, CodeDoc allows you to supply additional documentation topics (Web pages). CodeDoc allows you to define the overall structure of your table of contents (see below), and you can create a fairly arbitrary page hierarchy (tree) containing your pages. Note, however, that you can't insert additional pages within subtrees generated by CodeDoc. For example, CodeDoc creates a subtree corresponding to the members of each C# class—and you can't insert an additional topic into that subtree.

For each additional topic, you can specify one or more index entries which will appear (along with other index entries generated automatically by CodeDoc) in the "Index" tab of the DHTML-based documentation browser created by CodeDoc. For example, the page you're reading is listed in the index of this documentation set as "CodeDoc User Guide" and "User Guide". You can also make an index entry refer to a bookmark within a page.

Additional topics can be any type of file that can be displayed in a Web browser: HTML, Microsoft® Word, Adobe® PDF, etc. However, keep the following in mind:

If you write your additional topic pages in HTML, you're welcome to use CodeDoc's CSS style sheet file, "_CodeDoc.css", which is included automatically in the "pages" directory of the generated documentation set. Click here for an example of how to use "_CodeDoc.css" (opens in a new window). The advantage of using "_CodeDoc.css" is that it's easy to create pages that follow the same style as the pages generated by CodeDoc. A disadvantage is that "_CodeDoc.css" may change in future versions (renamed).

For more information about adding additional documentation topics to your documentation set, consult the following topics in the CodeDoc Project File Reference, or see the example below:

Creating a CodeDoc XML Project File

CodeDoc is controlled by an XML file called the CodeDoc project file. In order to use CodeDoc, you need to create a project file. The following project file is used to create the "ThermostatSample" sample project included in the CodeDoc download. Click here to view the CodeDoc-generated documentation browser corresponding to this sample (opens in a new window).

XML 
<CodeDoc xmlns="urn:schemas-dwell-net:codedoc:project-file">

    <ExternalReferences>
        <![CDATA[
        Exception
        List<>
        ]]>
    </ExternalReferences>

    <DeleteFilesInDirectory Path="Doc" />
    <DeleteFilesInDirectory Path="Doc\Pages" />

    <CreateDocBrowser
        BasicFramesetFileName="BasicBrowser.htm"
        FramesetFileName="Documentation.htm"
        NodeId="TocRoot"
        PagesRelativePath="Pages"
        Path="Doc"
        Title="ThermostatSample Class Library Documentation" />

    <DocBrowserStaticPages NodeId="TocRoot">
        <DocBrowserNode
            NodeId="TocOverview"
            Title="ThermostatSample Class Library API"
            Path="Overview.htm">
        </DocBrowserNode>
    </DocBrowserStaticPages>

    <ReadSource Path="ThermostatSample.cs" />

    <WriteDocumentation Path="Doc\Pages">
        <AddToDocBrowser NodeId="TocOverview" />
    </WriteDocumentation>

    <DocBrowserStaticPages NodeId="TocRoot">
        <DocBrowserNode
            NodeId="TocSource"
            Title="ThermostatSample Class Library Source Code"
            Path="SourceOverview.htm">
        </DocBrowserNode>
    </DocBrowserStaticPages>

    <ClearSources/>

    <ReadSource Path="ThermostatSample.cs" />

    <WriteFormattedCode Path="Doc\Pages">
        <AddToDocBrowser IndexLabelSuffix=" (Source Code)" NodeId="TocSource" />
        <SourceFilesNode
            Path="SourceFiles.htm"
            Title="Source Code Files">
        </SourceFilesNode>
    </WriteFormattedCode>

</CodeDoc>

The CodeDoc project file example above also contains the following XML elements. Note that the XML elements that are direct children of <CodeDoc> are processed in the order they appear in the file. (Other XML elements are essentially parameters.)

For more information on these CodeDoc XML project file elements, click the links above, or see the CodeDoc Project File Reference for full information about all supported elements. In particular, here are a few CodeDoc project file features not demonstrated by the example above:

Running the CodeDoc Console Application

CodeDoc.exe is a console application—you execute it from a command prompt. (In Windows® click Start, Run, type "cmd", click OK. Change to the directory where you unzipped CodeDoc into, using "cd /d directory-path", or add the directory containing CodeDoc to your PATH environment variable, or include the full path to CodeDoc.exe when you run it.)

Before running CodeDoc, ensure you have the Microsoft .NET Framework 2.0 installed. To do this, click Start, Run, type "%windir%\Microsoft.NET\Framework" (no spaces), click OK. If you have a folder named v2.0.50727, you have .NET Framework 2.0 (unless that folder only contains a few files, in which case it may have been uninstalled). To install the .NET Framework 2.0, go to Microsoft Update and click Custom to get non-high-priority updates.

Command-Line Example

To run CodeDoc, simply provide the name of the CodeDoc XML project file as the command-line parameter. For example, if you unzipped CodeDoc into C:\CodeDoc, you can run CodeDoc on the ThermostatSample project file describe above, as follows:

Command Prompt 
C:\CodeDoc> codedoc Samples\ThermostatSample\CodeDoc.xml   
Loading: ThermostatSample.cs
Enumerating topics to document
Converting XML to HTML
Writing 9 documentation topic(s)
Loading: ThermostatSample.cs
Enumerating topics to document
Converting XML to HTML
Writing 1 formatted source code file(s)
Writing TocRoot documentation browser
Done: 0 warning(s)

C:\CodeDoc>

This generates a CodeDoc documentation browser in C:\CodeDoc\Samples\ThermostatSample\Doc; open Documentation.htm to view the documentation. (Click here to view it now, in a new window).

When CodeDoc runs, it displays the names of source files it loads into memory, a count of documentation topics generated, and other information, including warnings (one per line) and a count of warnings generated.

Using CodeDoc From a Batch File

CodeDoc returns one of the following exit codes, which can be tested within a batch file using "if errorlevel":

Exit Code Description
0 Success—no warnings were displayed
1 Success, but one or more warnings were displayed
2 Failure
Running CodeDoc From Visual Studio

If you like, you can generate and view documentation from within Microsoft Visual Studio. If you do that, the warnings output from CodeDoc will be displayed in Visual Studio's Output window, and you'll be able to double-click a warning to go directly to the source code line containing the problem. To enable generating and viewing documentation from within Visual Studio, do the following (for Visual Studio 2005):

  1. Click Tools, External Tools.
  2. Click Add, and enter the following:
    • Title: Generate Documentation
    • Command: full path to CodeDoc.exe
    • Arguments: $(SolutionDir)CodeDoc.xml
  3. Click Add again, and enter the following:
    • Title: View Documentation
    • Command: C:\Program Files\Internet Explorer\iexplore.exe
    • Arguments: $(SolutionDir)Doc\Documentation.htm
  4. Click OK.

These settings assume the following:

CodeDoc Support Files

The directory containing CodeDoc.exe can be located anywhere on your computer. At a minimum, CodeDoc requires the following support files:

CodeDoc Limitations

The following is a partial list of the current limitations of CodeDoc. (There are undoubtedly many other limitations that neglected to get documented here.)

For More Information
Introduction to CodeDoc
CodeDoc XML Markup Reference
CodeDoc Project File Reference
Example: ThermostatSample
Next Topic: CodeDoc XML Markup Reference

Copyright (c) Eric Ledoux.  All rights reserved.  See http://www.dwell.net/terms for code sharing information.