Enabling XML-documentation for code contracts

One nice feature that code contracts offer is updating of code documentation. If you are using source code documenting features of Visual Studio then code contracts may automate some tasks you otherwise have to implement manually. In this posting I will show you some XML documentation files with documented contracts. I will also explain how this feature works.

Enabling XML-documentation in project settings

As a first thing let’s enable generating of code documentation under project settings. Open project properties, move to Build page and make check to checkbox called “XML documentation file”.

Save project settings and rebuild project. When project is built go to bin/Debug folder and open the XML-file. Here is my XML.

<?xml version="1.0"?>
<doc>
    <assembly>
        <name>Eneta.Examples.CodeContracts.Testable</name>
    </assembly>
    <members>
        <member name="T:Eneta.Examples.CodeContracts.Testable.Randomizer">
            <summary>
            Class for generating random integers in user specified range.
            </summary>
        </member>
        <member name="M:Eneta.Examples.CodeContracts.Testable.Randomizer.#ctor(Eneta.Examples.CodeContracts.Testable.IRandomGenerator)">
            <summary>
            Constructor of Randomizer. Initializes Randomizer class.
            </summary>
            <param name="generator">Instance of random number generator.</param>
        </member>
        <member name="M:Eneta.Examples.CodeContracts.Testable.Randomizer.GetRandomFromRangeContracted(System.Int32,System.Int32)">
            <summary>
            Returns random integer in given range.
            </summary>
            <param name="min">Minimum value of random integer.</param>
            <param name="max">Maximum value of random integer.</param>
        </member>
    </members>
</doc>

You can see nothing about code contracts here.

Enabling code contracts documentation

Code contracts have their own settings and conditions for documentation. Open project properties and move to Code Contracts tab. From “Contract Reference Assembly” dropdown check Build and make check to checkbox “Emit contracts into XML doc file”.

And again – save project setting, build the project and move to bin/Debug folder. Now you can see that there are two files for XML-documentation:

1. <assembly name>.XML
2. <assembly name>.old.XML

First files is documentation with contracts, second file is original documentation without contracts. Let’s see now what is inside our new XML-documentation file.

<?xml version="1.0"?>
<doc>
  <assembly>
    <name>Eneta.Examples.CodeContracts.Testable</name>
  </assembly>
  <members>
    <member name="T:Eneta.Examples.CodeContracts.Testable.Randomizer">
      <summary>
            Class for generating random integers in user specified range.
            </summary>
    </member>
    <member name="M:Eneta.Examples.CodeContracts.Testable.Randomizer.#ctor(Eneta.Examples.CodeContracts.Testable.IRandomGenerator)">
      <summary>
            Constructor of Randomizer. Initializes Randomizer class.
            </summary>
      <param name="generator">Instance of random number generator.</param>
    </member>
    <member name="M:Eneta.Examples.CodeContracts.Testable.Randomizer.GetRandomFromRangeContracted(System.Int32,System.Int32)">
      <summary>
            Returns random integer in given range.
            </summary>
      <param name="min">Minimum value of random integer.</param>
      <param name="max">Maximum value of random integer.</param>
      <requires description="Min must be less than max" exception="T:System.ArgumentOutOfRangeException">
                min &lt; max</requires>
      <exception cref="T:System.ArgumentOutOfRangeException">
                min &gt;= max</exception>
      <ensures description="Return value is out of range">
                Contract.Result&lt;int&gt;() &gt;= min &amp;&amp;
                Contract.Result&lt;int&gt;() &lt;= max</ensures>
    </member>
  </members>
</doc>

As you can see then code contracts are pretty well documented. Messages that I provided with code contracts are also available in documentation. If I wrote very good and informative messages then these messages are very useful also in contracts documentation.

Code contracts and Sandcastle

Sandcastle knows nothing about code contracts by default. There is separate package of file for Sandcastle that is provided you by code contracts installation. You can read from code contracts manual:

“Sandcastle (http://www.codeplex.com/Sandcastle) is a freely available tool that generates help les and web sites describing your APIs, based on the XML doc comments in your source code. The CodeContracts install contains a set of les that can be copied over a Sandcastle installation to take advantage of the additional contract information. The produced documentation adds a contract section to methods with declared requires and/or ensures.

In order for Sandcastle to produce Contract sections, you need to patch a number of files in its installation. Please refer to the Sandcastle Readme.txt found under Start Menu/CodeContracts/Sandcastle for instructions. A future release of Sandcastle will hopefully support contract sections without the need for this patching step.”

Integrating code contracts documentation to Sandcastle will be one of my next postings about code contracts.

Conclusion

if you are using code documentation then documentation about code contracts can be added to documentation very easily. All you have to do is to enable XML-documentation for contracts and build your project. Later you can use Sandcastle files provided by code contracts installer to integrate contracts documentation to your output documentation package.