I got to work a little bit on the Castle and I decided to concentrate on writing documentation. The Castle is really a good project and it’s a shame it's unpopular because it’s documentation is lacking. It’s design is so intuitive that in most cases once you understand the idea you won’t have to go back to documentation often.

nAnt is used by the Castle developers to build it. So I started off by adding tasks to generate documentation for all of the Castle sub-projects. The end result I wanted was a single CHM file with documentation for all assemblies. Simple, I thought, but I found out it’s harder than it looks. This brings me to the today’s post topic (finally, after 2 paragraphs, but I feel it’s appropriate to supply some background).

nAnt has a special task (task is one step in a build process) which uses nDoc to generate documentation from XML comments.

I thought I could just configure the task to iterate through all “bin” directories (all projects build into “bin” sub-folder of project’s folder). Iteration works OK, but it goes through all folders (those matching and not matching the pattern). In addition it also goes through all “.svn” folders (used by Subversion for source control) which practically doubles the number of folders nAnt traverses. According to documentation nAnt should've excluded “.svn” folders from traversal, but in this case it didn’t… I’m not sure why.

Another problem is that I only want to document actual release assemblies and ignore test assemblies (with “Tests” somewhere in the assembly name). nAnt decided to ignore my exclude pattern and just included everything.

The solution I came up with is to copy all assemblies to be documented to a separate folder. I hard-coded project folder names (yes, hard-coding is bad, but I could not find a way around it) and the process of selecting assemblies is very quick now. It still takes around 5 minutes on my computer to generate all documentation. There are more than 8000 class members to create HTML pages for, but it’s much faster than before.

Next phase is to add members’ documentation and examples to the code. I’m planning to start with Monorail and move on slowly. Mostly I aim for quality and not quantity. I don't want to go back often to redo it.