Finally, in Visual Studio 2005, Microsoft now supports XML Code Documentation. Visual Studio now ships with XDCMake.exe which creates XML Documentation files that we so enjoyed back in C#. Let's take a further look on how to use it.
First off, I created a new C++ CLR library in Visual Studio called AuditingLibrary. Once the project has been created, right-click on the project and go to the properties page. Notice on the left hand tree, that there is a XML Document Generator element. Expand that element and it should show you the following:
Now that we see this, let's just leave it alone. Each element is fully described in this link:
http://msdn2.microsoft.com/en-us/library/ms235515.aspx
Next, let's expand the C/C++ tree node, and go to the Output Files item. From there, flip the switch on Generate XML Documentation Files to Yes. Here is how it should look:
Now we must follow the same standards that C# uses. The full list of recommended tags are listed here:
http://msdn2.microsoft.com/en-us/library/ms177227.aspx
Now in our little example, I created a public value struct called AuditInfo. I put the summary tag on it that looks like this:
///
/// This class holds auditing information.
///
public value struct AuditInfo { ... }
Unfortunately, C++ gives us no sort of intellisense that the C# version does. This is a completely manual process which can be quite a pain. Now put the summary tags on the properties as well. Now, build the project and look at the results. The XDCMake tool created XDC files for each object that it compiles for XML document purposes. After the compilation, you can feel free to take a look at them. Now, let's look at the XML document that was created:
"AuditingLibrary"As you can see, it's very simple things. As you reference the library from any other .NET project, you now have the documentation available. Very simple stuff.