Visual Studio 2008 XML Comments...

Hi All,


I have just spent a very long time commenting a project in .NET using the XML comments available in VS 2008.


i.e. before each class, method or property declaration, you type three slashes (///), and VS will add a comment block for you that looks like this:


/// <summary>
///
/// </summary>

You then fill in a description, and when you build the project, a nice XML file is created containing the comments for you.


Using Sandcastle Help File Builder, you can then very quickly and easily create an MSDN style CHM/HTML file that will allow other developers to easily work with your code.


I digress...


The point I wanted to make was that in the service I am developing, there are two main projects:

• Main Service
• Settings

The settings project is a Windows Forms application that allows the users to configure the settings for the service, and then saves them to an XML file that is consumed by the service.

In most cases, I name the settings file "Settings.XML" for convenience.

So, I had added all my wonderful comments to my projects, and then realised that I wasn't outputting the XML comments file for the projects.

I turned this on my going to the Project Properties, then the build tab, and then ticking the: "XMLDocumentation File" checkbox.  This entered a default path and filename for the comments file.

It uses your BIN folder, then the build type [Debug, Release], then the project name followed by .xml.

i.e., for my settings project, the path was Bin\Debug\Settings.xml.


Right - I know, silly me for not changing the comments file output name then so it doesn't conflict with my own Settings.xml file (which resides in the project output folder as well...).


My moan is simple:  Visual Studio 2008 found the existing Settings.xml, assumed it was the comments file from a previous build, and continued to replace it without prompting!


Had to recreate my settings file from a backup and fill in the  missing bits...


Well - I hope this experience helps some of you out there who do the same - save yourself the pain - always append comments to your Comments XML file:

Mark