views:

198

answers:

1

I was mildly surprised recently to discover that my carefully crafted xml comments weren't showing up in intellisense for my colleagues. Having always used the associated assemblies with project references, I hadn't realised that you had to export the .xml document as well to access this information.

This led me to wondering how the .Net framework intellisense works. If I understand correctly, the .xml files must be hidden away somewhere in a special folder?

But my main question is about 'Goto definition' - if you goto definition on a .Net framework assembly, you get the info generated from metadata - but also with plenty of helpful comments - are these magically generated from Xml comments, or did someone have to write a macro + to convert them just for the build? Putting it differently: how can I get this effect for my assemblies?

A: 

Are your projects configured to generate the XML documentation? Just because you add the comments to the source code, the compiler won't generate the .xml file unless it's told to.

In the project properties page, go to the "Build" tab and look at the "Output" section. You should see a checkbox entry titled "XML documentation file". If textbox following that checkbox is empty you aren't generating the XML documentation file.

Once you get the XML documentation file generated, you should see your comments in the IntelliSense tooltips. If you include references to other projects as a project reference this should happen automatically. If you include references to assemblies, you need to ensure that the xml file is in the same location as the referenced assembly. (When you build, you should get xml files for all of the assemblies that have them in the bin/debug or bin/release folder respectively.)

For the .NET Framework assemblies themselves, the corresponding xml documentation files are installed as part of the Framework. For .NET 2.0, 3.0, or 3.5 the documentation files are located at C:\Windows\Microsoft.NET\Framework\v2.0.50727\en (assuming a default installation of the Framework). These files are used by both the IntelliSense tooltips and the "Go to Definition" functionality in Visual Studio in order to display this information. There is not any special processing that takes place or macros run in order to make this happen. The only information Visual Studio most likely uses is a combination of registry keys to determine the correct path to the documentation files.

While you probably could locate the xml documentation files for your own assemblies in the same folder, I would recommend against doing so as you then pollute the Framework installation with non-Framework related files.

Scott Dorman
Thanks, but I wanted to know about the framework assemblies - System.Drawing etc., where are the xml files for those? Can I put my xml files their? And where do the comments in 'generated from metadata' come from?
Benjol
Sorry. Misunderstood what you were asking. I've updated my answer.
Scott Dorman
Thanks for the extra info, but the last part of my question remains - where do the comments in the 'from metadata' View Definitions come from?
Benjol
The comments in the "generated metadata" files that display from the "Goto definition" menu also come from the xml documentation files that are installed with the framework. (See the last 3 sentences in the second last paragraph in my answer.)
Scott Dorman
My bad, sorry I didn't read properly :(
Benjol