Title: API Documentation made easy
Slug: api-documentation-made-easy
Date: 2008-07-30 15:23:00
Author: Kartones
Lang: en
Tags: .NET, Development, Tools
Description: A guide on using Sandcastle and Sandcastle Help File Builder to easily generate API documentation.

<p>It's been quite some time since I last used Continuous Integration servers and components, including reference (API/SDK like) documentation tools.</p> <p align="justify">But today at work, while fixing some warnings about incorrectly formed code comments ("<font face="Courier New"><b>///</b></font>" in C# or "<font face="Courier New"><b>'''</b></font>" 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</p> <p align="justify">So my next step was making him a small demo of <a href="http://www.codeplex.com/Sandcastle">Sandcastle</a>, the best documentation tool I've seen (I come from the now extinct NDoc).</p> <p align="justify">When Sandcastle was released publicly it had no visual GUIs, but now I'm amazed how mature they've become. I've chosen <a href="http://www.codeplex.com/SHFB">Sandcastle Help File Builder</a> as the GUI, because it is identical to the old NDoc's interface.</p> <p align="justify"><img src="https://images.kartones.net/posts/screenshots/sandcastle_hfb.png"> </p> <p align="justify">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.</p> <p align="justify">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.</p> <p align="justify">Here are the results of creating the documentation for a small project I did years ago:</p> <p align="justify"><img src="https://images.kartones.net/posts/screenshots/sandcastle_example_doc.png"> </p> <p align="justify"><br></p> <p align="justify">Note: Other two promising extensions I've not yet tested are <a href="http://www.codeplex.com/SandcastleStyles">Sandcastle Styles</a> and <a href="http://www.codeplex.com/sandextensions">Sandcastle Extensions</a>. Feel free to drop a comment if you've tried it telling what you think about them :)</p>
