.NET 1.1+

XML Documentation Comments

by Richard Carr, published at http://www.blackwasp.co.uk/XmlDocumentationComments.aspx

Documentation is important to ensure that developers can quickly learn and use code libraries. With XML documentation comments, the documentation can be embedded within source code using special mark-up that is recognised by Visual Studio's Intellisense.

Generating Documentation XML Files

So far you have seen that the information included in XML documentation comments can be viewed using Intellisense when working within the same solution. To allow the documentation for a compiled library to be referenced from other solutions, you must generate the XML file too. As long as the XML file is found in the same folder as the referenced assembly, Intellisense will present its information.

You can specify that you wish to create the documentation XML file using the project's property pages in Visual Studio. If you are using Visual Studio 2003, open the properties dialog box, select the "Configuration Properties" option and enter the XML file name in the "XML Documentation File" cell. It is recommended that the filename matches the name of the assembly, except for the extension. For example, if your project compiles a DLL named, "Calculator.dll", you should name the XML file, "Calculator.xml".

In Visual Studio 2005 or later, select the Build page of the project's properties. Tick the checkbox alongside the "XML documentation file" textbox to enable the XML file compilation. A path and name for the file will be populated automatically. In most cases you should use the provided name.

Once you have set the properties, compile the project. You should see that the XML file is generated in the same folder as the compiled assembly. Now when you reference the assembly, the XML information will be loaded automatically.