Using Sandcastle to build code contracts documentation

In my last posting about code contracts I showed how code contracts are documented in XML-documents. In this posting I will show you how to get code contracts documented with Sandcastle and Sandcastle Help File Builder.

Before we start, let’s download Sandcastle tools we need:

• Sandcastle
• Sandcastle Help File Builder

Install Sandcastle first and then Sandcastle Help File Builder. Because we are generating only HTML based documentation we upload to server we don’t need any other tools. Of course, we need Cassini or IIS, but I expect it to be already there in your machine.

Open your project and turn on XML-documentation for project and contracts.

Now let’s run Sandcastle Help File Builder. We have to create new project and add our Visual Studio solution to this project. Now set the HelpFileFormat parameter value to be Website and let builder build the help.

You have to wait about two or three minutes until help is ready. Take a look at your documentation that Sandcastle generated – you see not much information there about code contracts and their rules.

Enabling code contracts documentation

Now let’s include code contracts to documentation. Follow these steps:

1. Open Sandcastle folder and make copy of vs2005 folder.
2. Open CodeContracts folder (c:\program files\microsoft\contracts\) and unzip the archive from sandcastle folder.
3. Copy all unzipped files to Sandcastle folder.
4. Create (yes, create new) and build your Sandcastle Help File Builder documentation project again.
5. Open help.

In my case I see something like this now.

As you can see then contracts are documented pretty well. We can easily turn on code contracts XML-documentation generation and all our contracts are documented automatically. To get documentation work we had to use Sandcastle help file fixes that are installed with code contracts and if we had previously Sandcastle Help File Builder project we had to create it from start to get new rules accepted. Once the documentation support for contracts works we have to do nothing more to get contracts documented.