API Documentation made easy

It's been quite some time since I last used Continuous Integration servers and components, including reference (API/SDK like) documentation tools.

But today at work, while fixing some warnings about incorrectly formed code comments ("///" in C# or "'''" in VB.NET), I asked my project manager what tool they were using actually to generate the documentation. and they weren't using anything :P

So my next step was making him a small demo of Sandcastle, the best documentation tool I've seen (I come from the now extinct NDoc).

When Sandcastle was released publicly it had no visual GUIs, but now I'm amazed how mature they've become. I've chosen Sandcastle Help File Builder as the GUI, because it is identical to the old NDoc's interface.

To create the XMLs needed to build the documentation, just activate the "XML Documentation File" in the Build tab of your project's properties and re-compile it.

Add the XMLs to the Sandcastle help project (it will add the assemblies too, because it uses Reflection to obtain code, hierachy and other data), configure the project properties (name, file name, presentation style, if you want to generate documentation for private methods,...) and compile.

Here are the results of creating the documentation for a small project I did years ago:


Note: Other two promising extensions I've not yet tested are Sandcastle Styles and Sandcastle Extensions. Feel free to drop a comment if you've tried it telling what you think about them :)

Posted by Kartones on 2008-07-30

Comments?

Share via: Twitter Linkedin Google+ Facebook