Code Contracts – Generating documentation

As any other code element, code contracts need to be somehow documented to better understand their purpose in the existing code and to be able to design code that would interact with existing structures.

There are two ways to generate XML documentation for existing code contracts. The first one and the easiest one is to use the tools provided in Visual Studio. For example, I have this sample console application:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Diagnostics;
using System.Diagnostics.Contracts;

namespace ConsoleApplication
{
    class Program
    {
        static void Main(string[] args)
        {
            Car car = new Car();
            car.ChangeState();
            Console.Read();
        }
    }

    class Car
    {
        public bool isWorking = true;
        public bool isNot = true;

        [ContractInvariantMethod]
        void CheckState()
        {
            Contract.Invariant(isWorking);
        }

        public void ChangeState()
        {
            Contract.Requires(isNot);
            Random random = new Random();
            double result = random.NextDouble();
            isWorking = Convert.ToBoolean(Math.Round(result));
        }
    }
}

It has an invariant implemented as well as a Contract.Requires call.

Before generating the contract documentation, the general code XML documentation should be generated. In Visual Studio, this option is enabled in the application properties, in the Build tab:

In the same Properties dialog, in the Code Contracts tab there is the Contract Reference Assembly group box. That is the place where you need to look to generate the XML docs for the contracts that are present in the current assembly.

In order to be able to generate the XML file, you would need to build the reference assembly. Select the Build option from the list and check the Emit contracts into XML doc file. No contract documentation can be generated without this.

This will generate a CodeContracts folder inside the project folder, as well as a [AssemblyName].Contracts.dll – that is the reference assembly that is needed. Once you build the solution, inside the folder you will also see [AssemblyName].XML that will contain the XML representation of the documented code parts, contracts included.

For the above sample application, the XML will look like this:

<?xml version="1.0"?>
<doc>
  <assembly>
    <name>ConsoleApplication</name>
  </assembly>
  <members>
    <member name="T:ConsoleApplication.Car">
      <invariant>isWorking</invariant>
    </member>
    <member name="M:ConsoleApplication.Car.ChangeState">
      <requires>isNot</requires>
    </member>
  </members>
</doc>

You can clearly see where the contracts are placed, under which methods and classes as well as their type.

IMPORTANT NOTE: Do not name your assembly so that it ends in .Contracts. This will confuse the contract reference assembly builder and will eventually result in invalid data being generated.

The second way to generate XML documentation for existing contracts requires a bit more work, but eventually gives you more control over the process.

Once you install Code Contracts, you automatically get the ccdocgen tool, that generates XML–formatted documentation for the contract reference assembly. And this applies to the contract assembly only – don’t try this on your base assembly.

The ccdocgen is located in your %PROGRAMFILES%\Microsoft\Contracts\Bin folder (%PROGRAMFILES(X86)%\Microsoft\Contracts\Bin for 64-bit systems). Via this tool, the XML file can be generated by following this pattern:

ccdocgen –assembly [ReferenceAssemblyPath] –XmlFile [NameForXML]

The XML file will be generated automatically in the folder where the command prompt is currently pointing to. The XmlFile parameter is optional but I find it extremely useful because sometimes I want to give the XML file a more descriptive name, when I test multiple builds.

NOTE: In case you need to generate the reference assembly, you can use the ccrefgen tool, located in the same Bin folder with ccdocgen.