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: <assembly name>.XML <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 < max</requires> <exception cref="T:System.ArgumentOutOfRangeException"> min >= max</exception> <ensures description="Return value is out of range"> Contract.Result<int>() >= min && Contract.Result<int>() <= 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.
