Sandcastle is a Microsoft tool used to create MSDN like API documentation by reflecting over the source code assemblies and adding the XML comments included in the code. A new version of Sandcastle has just been released on CodePlex. The source code of the tool is available on CodePlex under the Microsoft Public License. Documenting the API is a highly recommended practice, even if the API is not made public, because the documentation will certainly be used internally by other developers. Such documentation is absolutely necessary if the API is to be made public.
Sandcastle was first announced back in 2006, and it has been in development for more than 2 years. There are currently only CTP releases, but a "1.0" release is to come in the near future. Another API documentation tool came from the open source NDoc project, whose development was discontinued a couple of years ago on announcement about Microsoft's desire to create Sandcastle. Other projects were built upon the legacy left by NDoc, like NDoc 2005 and NDoc3, but they are only in alpha development.
Sandcastle produces output similar to MSDN documentation as shown in this example. The key features of Sandcastle are:
- Works with or without authored comments
- Supports generics and .NET 2.0 Framework
- Is used internally by Microsoft to generate the .NET Framework documentation
- It can generate Visual Studio 2005, hana or prototype (CHM, HxS) types of documents
Sandcastle can be used from the command line or from a GUI to build the documentation. Instructions on using it can be found here. Sandcastle is a stand alone tool, so it works with any Visual Studio projects. There are plans to integrate it with Visual Studio, but a final decision has not been made yet. This version runs both on 32 bit and 64 bit machines.
