Friday, August 17, 2012

NDoc3 - a modern-day Lazarus

Back in the early days, the nDoc utility was the go-to solution for auto-generating API documentation for .NET applications. The build engine would parse the XML comments that the developer decorated class members with, and nDoc would take those results and produce MSDN-style web pages based on it. As an open source product, it attracted quite a following.
However, with the release of .NET Framework v2, nDoc failed to make the jump and instead imploded, being at the time quite a high-profile example of the risks of running an open source project:
  • the community might love your product, but if they don’t contribute something back (whether code, time or money) then it may not be possible for you to continue to develop it;
  • the vendor whose environment you are working in (in this case, Microsoft, but it could easily be another company. Apple, anyone?) can move into your space and deliver something that is good enough to draw mindshare away from your target audience. Actually, Sandcastle has never really been as good as, nor as easy to use as, nDoc, but the damage was done;
Fast-forward to the near-present time, and while Sandcastle continues to be unwieldy, the open source community is once again picking up the nDoc baton, this time in the form of nDoc3. In its current state, nDoc3 brings to the table support for .NET 3.5, but if you’re prepared to download the source code and build it yourself, you can get .NET 4 support as well. Of course, Microsoft moved the goalposts slightly this week with the release of .NET 4.5, so the cycle continues!
If you do want to try getting .NET 4 support, these are the steps that I had to go through (and a few hoops that I needed to jump through):
  1. Download the source code from Sourceforge, and extract the tarball to the file system;
  2. Rather than opening in VS2008 as the README file directs, I fired up VS2010;
  3. Building threw up a whole host of warnings, so I decided to try the provided NAnt build scripts;
  4. Building threw up a whole host of warnings, mostly about missing NAnt targets; in the end, I had to hack the file to pieces, first commenting out the references to the JavaDoc, Latex and LinearHtml documenters which, though references in the build file, don’t exist in the source code; I also had to comment out all the code related to testing, as again it referred to folders and/or files that don’t exist;
  5. I also needed to remove a duplicate AssemblyVersion attribute from Core\AssemblyInfo.cs;
  6. This at least allowed me to compile and run the application; however, when I tried to get it to document one of my own pieces of code, it quickly threw an exception which I traced back to an already-reported issue; fortunately, the user who raised the issue also submitted a patch, which while it has not been applied to the source tree, at least fixes the problem.
So now I have nDoc3 happily spitting out documentation for me; perhaps if time allows, I will look into writing a Wiki-format documenter.

No comments: