BT

InfoQ Homepage News Sandcastle: Generate .NET API Documentation

Sandcastle: Generate .NET API Documentation

Bookmarks

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.

Rate this Article

Adoption
Style

Hello stranger!

You need to Register an InfoQ account or or login to post comments. But there's so much more behind being registered.

Get the most out of the InfoQ experience.

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Community comments

  • Ndoc

    by Francois Ward /

    Your message is awaiting moderation. Thank you for participating in the discussion.

    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.

  • Good comments can't be replaced by automated tools

    by Jim Leonardo /

    Your message is awaiting moderation. Thank you for participating in the discussion.

    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.

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

BT

Is your profile up-to-date? Please take a moment to review and update.

Note: If updating/changing your email, a validation request will be sent

Company name:
Company role:
Company size:
Country/Zone:
State/Province/Region:
You will be sent an email to validate the new email address. This pop-up will close itself in a few moments.