Daryl Zuniga and Mike Barnett - Xml Documentation from Code Contracts for .Net
- Posted: Aug 10, 2009 at 3:55 PM
- 63,104 Views
- 12 Comments
Download
How do I download the videos?
- To download, right click the file type you would like and pick “Save target as…” or “Save link as…”
Why should I download videos from Channel9?
- It's an easy way to save the videos you like locally.
- You can save the videos in order to watch them offline.
- If all you want is to hear the audio, you can download the MP3!
Which version should I choose?
- If you want to view the video on your PC, Xbox or Media Center, download the High Quality WMV file (this is the highest quality version we have available).
- If you'd like a lower bitrate version, to reduce the download time or cost, then choose the Medium Quality WMV file.
- If you have a Zune, WP7, iPhone, iPad, or iPod device, choose the low or medium MP4 file.
- If you just want to hear the audio of the video, choose the MP3 file.
Right click “Save as…”
- High Quality WMV (PC, Xbox, MCE)
- MP3 (Audio only)
- MP4 (iPod, Zune HD)
- Mid Quality WMV (Lo-band, Mobile)
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.
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.
Comments Closed
Comments have been closed since this content was published more than 30 days ago, but if you'd like to continue the conversation,
please create a new thread in our Forums,
or
Contact Us and let us know.
Follow the Discussion
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.
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
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?
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)
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.
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.
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.
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.
i see
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
yeah, MEF is pretty powerful stuff. i didnt know you could plug into the intellisense bubbles as well though. (you are using MEF right?)
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
Yes, the idea is that the bubbles (adornments) should show up when you are writing an override of a virtual method in a supertype or an implementation of an interface method and you are going to inherit a contract from the overidden method or the interface method (respectively). Otherwise you might not be aware of it.
Hi guys,
I must say that you have done a great job with code contracts.
But unfortunately, I am having some problems with this Xml Documentation from Code Contracts. I have taken the same steps as Daryl on this video, but I am not able to get the contract tags into the xml documentation file. I am using 1.2.21023.14 version and tried it with both VS2008 and VS2010 Beta 2. There are no errors but simply contracts are not shown.
How should I resolve this issue?
Post your questions on code contracts at
http://social.msdn.microsoft.com/Forums/en/codecontracts/threads
Remove this comment
Remove this thread
close