C# Documentation

Coming from a C++ background, documentation in my source code was limited to sparse comments. At university we concentrated on Java programming, which has built-in support for javadoc tags. At first I didn't know anything about javadocs, or have any desire to use such a tool, but a tutor insisted that assignments come with full HTML documentation. The obvious conclusion to this is that I realised how valuable documentation could be, especially when it is written directly in the source code. This makes keeping documentation up to date more convenient, because it can be updated as the code changes.

Now when using Java or C++ I always document code, although I have never been as happy with the tools for C++ document generation as with javadoc. I think the main reason is that javadoc is so easy to use, and is often integrated with Java IDEs. Another reason is that I like the look and structure of the javadoc output, I always meant to put some work into customizing the output of my C++ documentation, but never got round to it.

I recently started using C#, and I thought having XML documentation as part of the language was a fantastic idea. The only problem is that there aren't any good tools available yet for generating HTML output. I spend hours trying out what was currently available (for free) last night.

The first program I tried was NDoc, which has been widely used in the past. Unfortunately it hasn't been actively developed for a while, and doesn't support .NET 2.0. I did find an alpha version with support, but I kept getting exceptions, and I wasn't impressed with the output.

I tried a couple other programs without much sucess, until I found a command-line tool by Microsoft called Sandcastle. From what I understand it is still in development for the next version of Visual Studio. That's why it currently takes a list of complicated commands to get anything to work. I downloaded a GUI tool for Sandcastle, but it just wouldn't work for me.

I guess what I really wanted was a tool for C# that was as easy to use as javadoc. For now I might just write a simple GUI for automating Sandcastle document generation. I would also like to customize the transformations, to provide a nicer output. I always hated the MSDN style documentation, it seems like a great way to hide information.