nCodian Documenter Lite

Summary:  nCodian™ Documenter Lite generates Html Help from a .NET assembly's XML documentation comments file. In its simplest use, click a single command, specify a single input file, and process all the way from XML to CHM. View screencast. Page Index: Input | Output Basics | Output Details | Limitations of XML Input File | Customization | Screenshots

Input

Visual Studio supports creation of XML documentation for projects. This requires basically two things. (1) The developer inserts in the assembly's source code XML comments for types and members in the assembly. (2) The project is compiled with the option to automatically emit the XML documentation into an XML file with the same name as the project and the .xml extension.

For more information, see MSDN Library for Visual Studio (XML Documentation Comments (C# Programming Guide), Documenting Your Code with XML (Visual Basic Programming Guide).

Assuming an assembly named MyAssembly, the output of the Visual Studio compiler which becomes the input file for nCodian™ Documenter is:

• MyAssembly.xml

Output Basics

nCodian Documenter consumes and manipulates the XML documentation file. It generates three categories of output files.

(1) A compiled Html Help file. This is the .chm file that is to be distributed with the assembly.

(2) Html Help project files. These are the HHP, HHC, and HHK files. The HHP file is the basic project file for an Html Help project. The HHC file is the table of contents file. The HHK file is the index file.

(3) The HTML files that the Html Help compiler uses as source files for each page of the .chm file. These include a page for each documented type and member in the assembly, types lists, all members lists, properties lists, methods lists, overloaded properties lists, overloaded methods lists, etc.

Assuming again an assembly named MyAssembly, the output files include:

• MyAssembly.chm

• MyAssembly.hhp

• MyAssembly.hhc

• MyAssembly.hhk

• Many HTML files

Output Details

• Html Help compiled help file (CHM)

• Html Help project files:  HHP (project), HHC (contents), HHK (index)

• Assembly page

• Types lists

• All members lists for members in types and at the assembly level

• Properties lists for members in types and at the assembly  level

• Methods lists for members in types and at the assembly level

• Overload lists and individual overloads of properties in types and at the assembly level

• Overload lists and individual overloads of methods in types and at the assembly level

• For .NET 2.0 and later, handles generics and duplicate types overloaded on type parameters

• Individual types pages

• Individual properties in types

• Individual methods in types

• Individual assembly level properties

• Individual assembly level methods

• On individual member pages:

  • summary

  • parameters

  • return value

  • remarks

  • see also (links to individual type page, all members list page, properties list page, and methods list page)

• Cross references

  • See Also cross references to

    • Type/class overview

    • All members list

    • Properties list

    • Methods list

  • From individual page for an overloaded member

    • Overloaded properties list

    • Overloaded methods list

• For overloaded members, can differentiate between a general member summary for the all members listing, properties listing, and methods listing and a specific overload member summary for the overload member listing and the individual member page, byuse of the <para> tag.

What is not supported in Lite version

• Fields

• Events

Limitations of XML documentation file

nCodian™ Documenter's sole input is the assembly's XML documentation comments file. It does not examine the compiled assembly itself, used reflection, decompilation, or any other source of information. This creates two classes of limitation for nCodian™ Documenter:

     1.  The general limitations of Visual Studio's XML documentation features. (For example, the flattening effects of XML documentation. MSDN says, "The XML file is not a hierarchical representation of your code; it is a flat list with a generated ID for each element.")

     2.  The limitations of how a user implemented XML documentation comments. For example, if a user forgot to comment a method, nCodian™ Documenter will not be able to output anything for the overlooked method. For another example, badly formed XML results in bad output.

Customization

In the generation of HTML output, nCodian™ Documenter uses:

• HTML templates

• Cascading style sheets

The application provides a default set of HTML templates and a default cascading style sheet that many users will find satisfactory. User can create customized templates and style sheets out side of nCodian™ Documenter and then, to use them, point nCodian™ Documenter to the location where they are stored.  In the default configuration, font attributes are controlled by CSS while background colors and table border colors are controlled in HTML.

In addition, nCodian™ Documenter includes a dialog that provides a graphical means of creating a set of HTML templates with customized background and table border colors. The dialog supports customizing:

• Background colors

• page

• page head

• column headers

• table cells

• Table border colors

• page head

  • border color light

  • border color dark

• member list

  • border color light

  • border color dark

Screenshots