Daryl Zuniga and Mike Barnett - Xml Documentation from Code Contracts for .Net

Posted By: Peli de Halleux | Aug 10th @ 3:55 PM | 58,621 Views | 12 Comments
Mike Barnett and Daryl Zuniga, a high school intern at RiSE, sit down to talk about Code Contracts for .NET and documentation. Daryl has been working this summer on a tool that inserts contracts elements into the Xml Documentation files generated by the C#/VB compiler. Daryl also updated the Sandcastle stylesheets so that the contracts appear in the documentation pages.

 Update: the xml comment generation is now available for download!

The Research in Software Engineering team (RiSE) coordinates Microsoft's research in Software Engineering in Redmond, USA.
Rating:
1
0
#Aug 10th @ 10:25 PM
Strilanc
Strilanc

I've already run into several cases where I've wondered why a method had no contracts on it (they were inherited from an interface). Having them automatically listed will definitely be a big help.

 

The xml documentation is also sure to be useful for MSDN, but having contracts show up in intellisense tooltips would be much handier.

#Aug 10th @ 11:26 PM
aL_
aL_
Rx ftw

cool, but i agree, its good but the way its implemented it wont show up in intellisense.. you could perhaps have an options to paste in the comments in the summary/params element instead of as new elements Smiley

 

what i dont get is how the contracts are turned into expressions, Requires() just takes a bool, not Expression<bool> (right?) how does that work? Smiley

#Aug 11th @ 5:06 AM
AdamSpeight2008
AdamSpeight2008
The Bandito Coder

From my understanding of how Code Contracts works is that they get rearranged at compiletime into the required positions, not at runtime which would require a Expression<Bool>.

 

Being a compile-time operation, the mechanics of code contract could use T4. (Is the correct?)

For example: A Requires get moved to the being of Method, A Ensure at the End.

 

The Result of an Expression is prodominatly a Boolean, but could be an Exception.

 

Lenght < 10 think as "Is Length < 10?" the possible answers are TRUE, FALSE (or Exception)

#Aug 11th @ 5:23 AM
dkallen
dkallen
JoJo, our pet rat

Does the the "green bubble" Daryl is working on serve your goal of seeing the contracts when you inherit? I am a bit unclear when/where the green bubble appears.

 

By the way, I'm glad Microsoft is hiring talented high school interns. I wish other business would give young people more chances like this. It's really important to their professional and personal growth.

#Aug 11th @ 7:26 AM
peli
peli
Peli

Neither of those (Expression Trees or T4). Code Contracts use CCI (http://ccimetadata.codeplex.com ) to read the MSIL byte stream and decompile the expressions and rewrite the bodies to insert runtime checks.

#Aug 11th @ 8:23 AM
Daryl.Zuniga
Daryl.Zuniga

At aL_:

You're exactly right, you can get them to show up by patching into the summary tag, in fact I've already got code for CCDoc that does just that. However, with VS2010 we can do even better, with some of their new extensibility features you can now add additional information into an IntelliSense QuickInfo bubbles, however this won't be available until beta 2.

 

At dkallen:

You’re right, the "green bubble" is meant to help you when you're implementing an inherited method that has contracts so you know exactly what those contracts are. Our "green bubble" will only appear if you’re inheriting from an interface/class that is in a compiled assembly (i.e. not in your current project) because the code contracts tools work by decompilation.

#Aug 11th @ 8:39 AM
peli
peli
Peli

The problem with patching summary tag is that it does not work for projects loaded in the solution. The C# parser does not read the xml doc file and uses some internal parse tree.

#Aug 11th @ 12:58 PM
aL_
aL_
Rx ftw

i see Smiley does that mean that the variable names are lost if the dll is not built with debug info? will CC use generic variable names in that case or what? (in contract violation exceptions i mean)

 

@Daryl

ok cool Smiley yeah, MEF is pretty powerful stuff. i didnt know you could plug into the intellisense bubbles as well though. (you are using MEF right?)

#Aug 12th @ 8:10 AM
Daryl.Zuniga
Daryl.Zuniga

The CodeContracts tool chain builds its own "contracts" dll (i.e. filename.contracts.dll) that contains all the contracts information that CCDoc or other contract tools need and it must be present in order for them to work. This contracts dll is automatically built if you check the "Build a Contract Reference Assembly" in your CodeContracts settings in VS (similar to the "Emit contracts into XML doc file" option I talked about in the film).

 

Yes, it's all done with MEF. You can't currently plug into the IntelliSense bubbles, but hopefully in beta 2 or so you will be able to Smiley

Microsoft Communities