DevIL's Diary: NDoc is dead

While working on the next release of the Common.Logging library, I noticed that we didn't have an API documentation yet. On Spring.NET we use DocumentX (alas in the outdated version 2005) to generate the SDK documentation, thus I tried to set this up for Common.Logging. Quickly I faced some issues: First we do have a free Open Source project License for Spring.NET, but I'm not sure, if I can reuse it for another framework. Second, you can't run DocX from the commandline (except when you explicitely ask Innovasys for it). This is a no-go for continuous integration.

Any Open Source Alternatives?

Looking for alternatives - as an OSS guy of course I prefer an OSS tool, I couldn't find much. Being burned a while ago by Sandcastle and very irritated about MSFTs seriousness on this tool, the only tool I could find and that was at least close to what I expected was NDoc3. My expectations were low: I want to be able to integrate it in my build script and the documentation process should be tightly integrated with my daily development work.

Getting involved

Being the successor of my formerly beloved, but now dead, NDoc tool, thanks to Kim Christensen picking up the project, NDoc3 is capable of handling new .NET 2.0 features like generics, asymetric property accessibility etc.. For those familiar with NDoc, there won't be any surprises. Guides for using NDoc can e.g. be found here. Being not 100% satisfied with it yet, I did what OSS is all about: I involved myself in the further development of NDoc3.

What's new?

After a week of hard work, I refactored the codebase to allow for better development in the future as well as better testing. In addition, I introduced a new feature: MergeAssemblies. This means that similar to DocX, it is now possible to generate an extra hierarchy level for assemblies. By default, the flag is on, but you can turn it off:

This results in a navigation hierarchy created as shown below:

This also allows for yet another nice feature: the assembly overview page. It provides a complete overview of your assembly's references, dependencies and all types. Here is an examples of how this looks like:

To allow for automatically generating the assembly summary text, I introduced a new AssemblyDoc class (similar to the NamespaceDoc feature). Just add a class named AssemblyDoc to the global namespace in your assembly:

1:

   2:  /// <summary>

   3:  /// This assembly contains the adapter to the

   4:  /// NLog 1.0.0.505 library

   5:  /// </summary>

   6:  internal sealed class AssemblyDoc

   7:  {

   8:      // serves as assembly summary for NDoc3 (http://ndoc3.sourceforge.net)

   9:      private AssemblyDoc()

  10:      { }

  11:  }

and remember to activate the "UseNamespaceDocSummaries" setting! Hopefully you will soon see a full-fledged example project soon when we release Common.Logging 2.0 in the next couple of days.

Cool - I want it for my own projects!

First of all, all these features just work for the MSDN documenter yet. Since unfortunately there is no nightly build set up yet (any volunteers out there?), you need to grab the code from SVN and simply execute the nant script in the root folder of the trunk - see the readme.txt file for more info. Note, that you need a recent nightly build of NAnt, that supports .NET 3.5. Alternatively you can open the solution file and build the solution using VS2008.