Click here to Skip to main content
Click here to Skip to main content

XML Comments for Managed C++ Applications

, 9 Nov 2004
Rate this:
Please Sign up or sign in to vote.
Visual Studio .NET Add-in allowing XML style comments in Managed C++ applications.

Introduction

Most of my application development these days is in C#. Over the past two years, I have grown accustomed to the C# XML comments built into the C# editor. As we all know by now, you can edit the project properties of your C# application and define an XML documentation file. With that processed XML file and the compiled assembly, NDoc can automatically build a Windows help file for your software.

There are days, though, when I have to leave the friendly confines of C# and drop down to C++. When this happens, I am usually writing a managed C++ class that hides unmanaged functionality (for example, serial port access). At that point, though, we have lost our ability to use XML commenting of our source code. Without XML commenting and the processing of those XML comments, we cannot use NDoc for that subsystem. That is a real problem, given that 90% of my projects are C# and documented in NDoc!

A while back, I wrote a Visual Studio Add-in (in C#) that handles XML commenting for managed C++ applications. It allows you to type XML comments. When the assembly is compiled, it processes the XML comments and builds a processed XML file that can be used as input to NDoc. This way, I can consistently comment all of my source code!

Writing Add-Ins

Support for add-ins in Visual Studio exists in the form of an "extensibility" project called "Visual Studio .NET Add-in". I will not cover the nuances of creating add-ins. If you want a good book on the subject, refer to the book "Developing Visual Studio .NET Macros and Add-Ins" by Jeff Cogswell. It is one of the few references I found.

Once you create an add-in project, you can then create event handlers for the specific events that are relevant for your add-in. There is an extensive object model describing the layout of the Visual Studio environment, solutions, and projects.

Two Areas To Address

When designing this add-in, there were two separate areas of concern. The first is to provide support for entering XML comments into source code. As we all know, when you start typing '///' in the C# editor, it automatically will expand if it precedes a method or property definition. I wanted to try to maintain a similar user experience.

The second area to address is the processing of those XML comments in order to build the XML comment files that can be used by NDoc.

Entering XML Comments Into Source Code

The first decision I made was that XML comments would be added to the header file. That is where all methods and properties will be defined, so naturally it is a logical place for the user to enter the XML comments. When I created the project, I was hoping to find an event that would fire each time the user pressed a key in the editor. However, that level of notification does not exist. I quickly discovered that the only editor event that came close was a line changed event from the TextEditorEvents object. This event gets fired every time the line number changes, including when the enter key is pressed.

Practically, this means that we cannot duplicate the exact behavior of the C# comment completion feature. The best that could be done is to make a check for '///' when a line changes. Hence, if you type '///' then press the enter key, the add-in will determine if XML comments are appropriate. If so, then it will expand the section to look like the familiar:

///<summary>
///
///</summary>
CSerialPort(void);

From there, you can enter a summary comment.

As noted above, when you enter a new comment section, the code in the Line Changed event will scan the editor to see if the comment is before a function or a variable definition. If it determines the target is a function, it will attempt to decode the parameters of the function and build the appropriate XML comment structure. For example:

///<summary>
/// 
///</summary>
///<param name="port"> </param>
///<returns> </returns>
bool    Open(int port);

If you are in the middle of an XML comment section and you press Enter, it will recognize your position and automatically add '///' to the start of the new line and space it with the other comment tags in the section. For example, in the example above, if the cursor was at the end of the 'param name = "port"' line and you pressed Enter, the comment section would look like this...

///<summary>
/// 
///</summary>
///<param name="port"> </param>
///
///<returns> </returns>
bool    Open(int port);

Processing XML Comments to make the XML File

After the XML comments are entered into the header file, they need to be processed to create the XML comment file. To do that, I create an event handler to monitor the Build Done event for the project. Whenever a project is built, that event will fire and the add-in is notified. It will check to make sure that the XML comment file should be built. It only builds the comment file for managed C++ projects that have been successfully built.

The building of the XML file is fairly straightforward. When the project is built, the compiler creates a data structure that describes all the entities associated with the code. Every property, method, enumeration, namespace, etc. is represented as a CodeElement. We can examine the CodeElement object for the project after it is built, to get a list of all entities in the project. We can iterate through the object list and examine the Kind each element represents. Based on the type, we create nodes in the XML document object that follows the format for the XML commenting scheme.

The code is not perfect

I developed this code rather quickly. Like most of us, I do not have time to make it perfect. It does what I need it to do.

There was one area in particular I wanted to address, but was unsuccessful. The way the add-in works now, the XML comment file will always be built if you are compiling a managed C++ application. The file it creates is based on the project file name. The file is always placed in the active configuration directory. For example, if the project is called 'MyProj' and you are building a Release build, the XML file will always be "Release/MyProj.xml". What I tried to do was build a project extender property that would allow you to specify the XML file name and location. I was unsuccessful in getting that done. If anyone has suggestions, let me know.

Limitations

The add-in assumes that attribute definitions are defined immediately preceding a function definition on the lines above the function. When processing the code, the add-in examines each line using a simple Regex.IsMatch function. When looking for attributes, it uses "\\[(.)*\\]".

History

  • 5/14/2004 - Corrections for bug when processing function parameters.
  • 5/20/2004 - Added exception handling and stack trace when failure occurs.
  • 5/26/2004 - Handles interface documentation. Fixed misc. bugs in decoding parameter text.
  • 8/09/2004 - Attributes are now handled. See 'Limitations' section above for more details.
  • 9/22/2004 - Updated based on user feedback. Should fix problems with enumerations and parameters. Many thanks to M Ward and FredericM102LI90.
  • 11/09/2004 - Fixed exception being thrown when no .h file exists. Thanks to barrd for pointing this one out.

License

This article has no explicit license attached to it but may contain usage terms in the article text or the download files themselves. If in doubt please contact the author via the discussion board below.

A list of licenses authors might use can be found here

Share

About the Author

Jay Nelson
Web Developer
United States United States
I have been developing software professionaly since 1991 writing software in Automation and Manufacturing environments. For 14 years I worked for companies that built custom robotic automated equipment for the semiconductor, telecommunications, and other industies. Presently, I work for a medical device manufacturer developing applications for the compact framework.
 
My undergraduate degrees are in Mathematics and Philosopy. My graduate degree is in Management Information Systems. I am MCSD certified in Visual C++ 6.0 and MCSD.NET certified in C#.
 
I enjoy triathlons and reading.

Comments and Discussions

 
GeneralVS2008 PinmemberLeslieB9-Dec-09 2:24 
GeneralRe: VS2008 PinmemberMember 442466824-Dec-11 9:22 
GeneralCannot install for VS 2005 Pinmemberpotrto13-Apr-07 0:00 
GeneralRe: Cannot install for VS 2005 Pinmembermfgreen7719-Apr-07 5:31 
GeneralRe: Cannot install for VS 2005 PinmemberDEGT16-Nov-07 6:07 
GeneralRe: Cannot install for VS 2005 Pinmembermfgreen7717-Nov-07 12:23 
GeneralRe: Cannot install for VS 2005 PinmemberDEGT18-Nov-07 22:14 
GeneralRe: Cannot install for VS 2005 Pinmembermfgreen7720-Nov-07 3:48 
GeneralNew version of MCXDoc for VS2005 (/clr:oldSyntax) [modified] Pinmembervoid12320-Dec-06 7:02 
GeneralRe: New version of MCXDoc for VS2005 (/clr:oldSyntax) PinmemberJames.Love2-Jan-07 9:23 
GeneralRe: New version of MCXDoc for VS2005 (/clr:oldSyntax) Pinmemberujos4-Jan-07 23:23 
General#include from unmanaged header file causes error [modified] Pinmemberstempsoft19-Nov-06 18:06 
GeneralRe: #include from unmanaged header file causes error Pinmemberstempsoft22-Nov-06 11:53 
GeneralUnable to extract XML: Edit Point not found Pinmemberstempsoft19-Nov-06 17:22 
QuestionXML documentation for console application? Pinmemberminzhu127-Jun-06 16:59 
AnswerRe: XML documentation for console application? PinmemberJay Nelson28-Jun-06 4:03 
AnswerRe: XML documentation for console application? [modified] Pinmemberminzhu128-Jun-06 5:20 
GeneralAdd-in for documenting C++ Code [modified] Pinmembermarcoow7-Jun-06 5:03 
QuestionHow to show right root page! Pinmembertrongnghiavc18-May-06 22:11 
QuestionNDoc support Framework 2 ? PinmemberRedaemon22-Jan-06 6:39 
AnswerRe: NDoc support Framework 2 ? PinmemberStephan Brenner26-Jan-06 5:27 
QuestionProblem generating documentation PinmemberIsaacB20-Dec-05 9:41 
AnswerRe: Problem generating documentation Pinmemberjstevenco28-Dec-05 14:26 
AnswerRe: Problem generating documentation Pinmembervoid12314-Aug-06 22:33 
GeneralThanks Pinmemberbrtna25-Apr-05 21:44 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.

| Advertise | Privacy | Terms of Use | Mobile
Web02 | 2.8.1411023.1 | Last Updated 9 Nov 2004
Article Copyright 2004 by Jay Nelson
Everything else Copyright © CodeProject, 1999-2014
Layout: fixed | fluid