6/20/2008 5:31 AM
API documentation may be of great importance to a project. Especially when the project is a library intended for use by other developers. As a rule such documentation is represented in a form of help files (*.hxk for instance) or in a form of HTML pages contating reference for all project's namespaces, classes and etc.
However neither .NET framework nor Visual Studio contain tools for creating API documentation. Instead, developers need to address some separate tools for this aim.
For a long time NDoc tool has been the best choice to generate API docs from source code comments. It is fast, reliable, easy-to-use and free. But unfortunalely NDoc project was freezed and is not supported anymore. It works only with .NET 1.1 projects.
Sandcastle is a free documentation generating tool from Microsoft. Although functional and powerful, it has some drawbacks:
- It does not come as a standalone tool. A separate GUI application is needed to comfortably use Sandcastle (e.g. www.codeplex.com/SHFB).
- Documentation generation takes more than 10 minutes for a middle-sized project.
These two make Sandcastle rather cumbersome solution.
Also worth looking at is a commercial documentation generation tool named Doc-O-Matic. Its much faster and more usable than Sandcastle, although quite expensive.