Improved Method Documentation for Visual C++

• Download source files - 45 Kb
• Download demo project - 23 Kb

Introduction

In my previous documentation article Method Documentation Utility for Visual C++ 6 I received comments that the Add-in does not support Doxygen format. The truth is that it didn’t support any format, it was totally hard coded.

This new Add-in gives the user the option to decide his own format for the documentation using a simple configuration screen. The default format will be Doxygen.

Description

Like the previous Add-in, here you will be able to press a toolbar button (or any shortcut key you assigned to it) and a skeleton for documentation will appear above the method/function. The documentation will contain the following parts:

• General – general description of the method
• Return value – explain what will be the return value
• Parameter – any parameter can be documented
• See also – reference for another method or parts in the code
• Documentation start – beginning of documentation
• Documentation end – end of documentation

The Doxygen format which most of you know and it’s the default format for the Add-in look like this:

//! Method description
/*!
\param nF - description
\param nS - description
\return bool - description
\sa func2()
*/
bool func(int nF, int nS);

There are other formats but I chose this one because I am used to it.

All you have to do to generate the documentation is to put the cursor one line before the method or on the same line as the method like this:

[Cursor Here] 
bool func(int nF, int nS); 

Then press the Add-in's left button or your selected keyboard shortcut.

The Add-in extracts the method’s text. It starts with the next line of the cursor and collects the text until it reaches ‘)’. It then parses the text. Currently I am parsing only the return value and the parameters list. If any need for additional information like: virtual/const will arise it will be added to the tool.

Customizing The Documentation

The customization dialog looks like this:

To reach this screen, just press the right button of the addin.

Here you can change the template of the documentation. It is based on tags, each tag represents a different element in the documentation:

Parameter, returned value...

To change the value of a tag just select the tag and enter your own text in the textbox at the buttom. The right box shows you an example of how the documentation will look like.

Installing the Add-in

To install the binary and use it under Visual C++ 6 please read the Readme.txt file added in both zip files

The code was tested under Windows2000/XP only and it may work under windows 98 but who knows for sure…