Geeks With Blogs
Blog Moved to http://podwysocki.codebetter.com/ Blog Moved to http://podwysocki.codebetter.com/
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:
 
 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:
 
Now in our little example, I created a public value struct called AuditInfo.  I put the summary tag on it that looks like this:
 
/// <summary>
/// This class holds auditing information.
///</summary>
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:
 
<?xml version="1.0"?>
<doc>
    <assembly>
        "AuditingLibrary"
    </assembly>
    <members>
        <member name="P:AuditingServices.AuditInfo.AccessTime">
            <summary>
Gets or sets the access date time.
</summary>
        </member>
        <member name="P:AuditingServices.AuditInfo.RemoteIP">
            <summary>
Gets or sets the remote IP address.
</summary>
        </member>
        <member name="P:AuditingServices.AuditInfo.LogonName">
            <summary>
Gets or sets the logon name.
</summary>
        </member>
        <member name="T:AuditingServices.AuditInfo">
            <summary>
This class holds the auditing information.
</summary>
        </member>
    </members>
</doc>
 
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.
 
Posted on Wednesday, May 17, 2006 11:23 AM Microsoft , .NET | Back to top


Comments on this post: C++/CLI and XML Code Documentation

No comments posted yet.
Your comment:
 (will show your gravatar)


Copyright © Matthew Podwysocki | Powered by: GeeksWithBlogs.net