NDocProc - Javadocish documentation for .NET

Introduction

There are a few tools for building javadoc-like documentation for .NET code available out there on the 'net. Unfortunately, the major contenders (e.g. NDoc, Sandcastle) suffer from a few flaws: they are variously not free (gratis), not free (libre), not cross-platform, not maintained, and/or not easy-to-use.

• Tiny. Simple.
• Very easy to extend, repair, or modify.
• Very easy to produce output with a custom appearance, via XSLT and CSS stylesheets.

• Uses google's "I'm Feeling Lucky" for types it doesn't know about! (This works surprisingly well.)
• Uses Microsoft's XML documentation comments (see here and here)
• Runs on Mono as well as Microsoft's .NET

• Doesn't format the comments into HTML very nicely yet - for the most part, simply transposes them into the HTML without modification. The "<para>" tag is the only current exception.
• Support for generics is present, but minimal. There are certain to be things I've forgotten.

Downloading

NDocProc is available as a mercurial repository:

      hg clone http://hg.opensource.lshift.net/ndocproc
    

Occasional source/binary snapshots are made, and are usually found buried somewhere on this page (look for ndocproc-YYYYMMDDHHMM.zip). Periodic NDocProc-related announcements will be made on the "our software" category of LShift's blog.

Open-source license

Copyright (c) 2007, LShift Ltd. <query@lshift.net>
Copyright (c) 2007, Tony Garnock-Jones <tonyg@kcbbs.gen.nz>

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.

Examples

• The documentation for class OneHello illustrates many of the features of NDocProc's output.
• html/ - the HTML output by the XSLT stylesheets that come with NDocProc

• xml/ - the XML output by the NDocProc program
• Examples.cs - C# source code containing the example documentation
• namespaces.xml - handwritten documentation for the namespaces in the example project
• examples.xml - generated from Examples.cs by the /doc option to csc or mcs

For an example of driving NDocProc from within a NAnt build script, see the NDocProc build script, which includes a target called examples which

1. compiles Examples.cs with /doc
2. processes the resulting XML, and namespaces.xml, with NDocProc
3. transforms the resulting XML into HTML with XSLT stylesheets

Compiling

You will need:

• Mono, or Microsoft .NET SDK
• NAnt 0.85

Once you've downloaded the source, copy local.build.example to local.build, and edit it to point to one of the files in the configs directory.

The only really interesting setting in a configs build file is the target.framework setting, which can be any of

• mono-2.0
• dotnet-2.0

Run NAnt, and it should compile NDocProc.exe and build the example DLL and documentation. Build products will appear in the build directory (e.g. build/bin/ndocproc.exe).

To remove build products, run nant clean.

Caveats

When documenting implementations of interface methods that explicitly specify which interface the method is for, MCS has a bug where the emitted XML documentation uses the wrong namespace. To work around it, fully qualify the interface:

      using System;

      public class Broken: System.ICloneable {
        ///<summary>This doc string will not be found, because I
        ///should have said "System.ICloneable", even though the
        ///compiler knows perfectly well that System.ICloneable is
        ///what I meant.</summary>
        public object ICloneable.Clone() {
	  return null;
	}
      }

      public class Fine: ICloneable {
        ///<summary>This doc string will be found, because I used the
        ///literal text "System.ICloneable".</summary>
        public object System.ICloneable.Clone() {
	  return null;
	}
      }
    

See also Interfaces.cs, and its generated documentation.