Sandcastle: Generate .NET API Documentation

Posted by Abel Avram on Feb 04, 2008

Sections

Development

Topics

Artifacts & Tools ,

Tools ,

.NET ,

Sandcastle ,

Agile ,

Documentation ,

Programming

Share |

RELATED Research

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.

RelatedVendorContent

The Agile Tester

Visual Studio vNext: ALM features for Agile Planning, Team Collaboration

RDBMS to NoSQL: Managing the Transition

Adopting Git for the Enterprise: Risks and Considerations

Branching & Merging Efficiently: A Guide to Using Process-Based Promotional Patterns

Related Sponsor

In today’s hyper-competitive world, later may be too late to adopt Agile development and this Roadmap for Success will help you get started. Download "Agile Development: A Manager's Roadmap for Success" now!

1. Back to top

   Ndoc

   by Francois Ward

   Was NDoc development really discontinued because of the announcement of Sandcastle? I didn't follow this whole thing in a bit, but back then, NDoc's development was stalling because of author-related reasons (I beleive he asked for help and not enough people did or something? Among other things? I forget...), and then Microsoft's blogs, community forums, and all these outlets started being -flooded- with requests for Microsoft to give us a tool like Javadoc for Java (that is, built in).
   
   Eventually they caved in and announced Sandcastle. May not be how it went, but its the way I saw it.

   Reply

2. Back to top

   Good comments can't be replaced by automated tools

   by Jim Leonardo

   I hope this for packaging purposes and isn't intended to produce the following:
   
   Method name: GetUserFromProfile
   
   Documentation : Gets the user from the profile.
   
   That's useless at best (you got all that from the descriptive method name). At worst, its being passed of as proper documentation so some slacker programmer who never comments code can say they do documentation and thereby bamboozle some overloaded manager who has to make sure 10 developers are producing everything they are supposed to. Of course, said slacker also probably came up with a method name that was more along the lines of GetUser or gusr.

   Reply