Thursday, April 10, 2008

VS 2003 XML Comments & Intellisense

If you're like me, you create a class and then not 5 minutes later forget some details about it and having Intellisense would help you remember not only what the class is for, but what each property in the class is used for as well.

Have you ever added XML commenting to your project, and then noticed that those comments don't show up in Intellisense? Something like this:

clip_image002

In-between the <summary> tags are details you can include about the class/property/etc.

Notice though, when you mouse over a reference to that class in your code, your nice little summary comment doesn't show up, only the header shows:

clip_image004

Having these comments show up isn't a default setting in Visual Studio 2003, you need to enable them before they will be displayed. To do so, right click on the project in the Solution Explorer, then go to Properties. In the properties window, click on Configuration Properties and make sure Build is the one selected. At the bottom, you'll see a field in the Outputs section called XML Documentation File. It's probably blank. You need to tell it what the settings file will be named. This should be the name of your project with a .xml extension. So in my project, this would be:

clip_image006

After you do this, rebuild the project (not build, rebuild will actually generate the XML file, build does not from what I can determine). This will create an xml file in the project's folder:

clip_image008

Please note that changing this setting will cause anything that hasn't been commented to have a warning generated when you compile the code. This doesn't stop the compile from happening and it doesn't show up in the Output window since it's only a warning, but on any publicly visible types or members that don't have a comment you will have the blue underline with this comment:

clip_image010

This doesn't affect your project adversely at all, I just thought I should mention this so that if you decide to use this technique, but don't want to comment everything, you may see some of this behavior.

If you currently had a reference to the project before you rebuilt it with the changes made to generate the XML file, you will have to delete that reference and re-add it in order for the comments to be picked up. If you make any changes to the summaries, it requires you re-add the references each time to show the changes made. I'm not sure why this is, and I'm researching to see why this is required.

Now when you mouse over the reference, you should see your comment:

clip_image012

This is a nice intro to C# and XML source code documentation.

http://www.codeproject.com/csharp/csharpcodedocumentation.asp

MSDN entry on the /doc tag for the compiler, as well as links to how the XML documentation file works.

http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cscomp/html/vcerrDocProcessDocumentationComments.asp

No comments: