The new release of Code Contracts is out and brings a very cool feature: Xml comment generation. This means that you do not have to worry about keeping the comments in sync with the code, the compiler takes care of this.

Contracts to Xml Comments in action

Unless you invest a lot of work in them, Xml comments are most often worthless. For example, in QuickGraph, the documentation of the Edge constructor is really… well… useless (oops my fault):

However, the body of the constructor contains Contracts that state the pre-conditions and post-conditions of the constructor: source and target should not be null, etc… With the new xml comment generation, these contracts will be added to the xml documentation and ultimately will show up in the compiled documentation.

First, let’s turn xml comment generation on in the property pages:

Once the project is rebuilt, we can take a look at the generated xml documentation file. The ‘requires’ and ‘ensures’ elements are now under the Edge constructor element:

Finally, we run the documentation file through Sandcastle*** to get the final result (make sure you update the Sandcastle stylesheets that come with Contracts. Read section 8 of the documentation):

Voila! With this feature, you have a documentation that never goes out of date.