Commenting Functions and Mutiple Lines in Visual Studio 2005

Commenting Functions

A macro can create any function comment from any function definition. A macro hardly can determine function definitions, including calling conventions, full return types (including spaces in types between '*' and '&' and "const" specifier), parameters lists, function names, and so on. Also, a macro enables its flexible adjustment; in other words, you easily can change the text of any block, adding additional places for the comment and even changing positions or, in general, remove some blocks. There are seven blocks that you can change at any time to any text:

  1. Header of function comment (or simply delimiter): Usually used to delimit code and function comment. The default value is:
    Dim StrDelim As String = _
    "// -=-=-=-=-=-=-=-=-=-=-=-=-=-"
  2. Function name: A template for the output block of the function name. In this string, there must be "%s" chars that will be replaced by the function name. The default value is:
    Dim StrFunc As String = _
    "// Function [%s]"
  3. Function return type: A template for the output block of the return type, In this string, there must be "%s" chars that will be replaced by the function return type. The default value is:
    Dim StrRetType As String = _
    "// Return type [%s] - "
  4. Function calling convention: A template for the output block of the function calling convention. In this string, there must be "%s" chars that will be replaced by the function calling convention. The default value is:
    Dim StrCallConv As String = _
    "// Calling convention [%s] - "
  5. Function specifier (static, virtual, extern): A template for the output block of the function specifier. In this string, there must be "%s" chars that will be replaced by a function specifier. The default value is:
    Dim StrSpecifier As String = _
    "// Specifier [%s] - "
  6. Function description block. The text that will be inserted, as descrubed for commenting the function. The default value is:
    Dim StrDesc As String = _
    "// Description: " + CStr(CrLf) + _
    "//     " + CStr(CrLf) + _
    "//     "
  7. Function parameters list: There are two variables that link with this block. First, text that will be inserted before paramaters list; and second, the template for one function parameter. The default values are:
    Dim StrParams As String = _"// Parameters: "
       Dim StrParam As String = _
       CStr(CrLf) + "//     [%s] - "

Customizing Templates

As I said, you can specify any text for templates. In other words, you can insert (line-feed, caret-reset) characters when you need a multiline template; this will be inserted without any problem. Also, you can change the parameters list template so that all parameters will be inserted in a single line with a delimiter that you specify in the template string. Here are some samples:

Dim StrFunc As String = _
   "// Function [%s]" + CStr(CrLf) + "//     "

Dim StrParam As String = "(%s) - ."

Dim StrRetType As String = "// Returns : %s "

Calling Conventions and the Specifiers Words List

Because I didn't find a way to determine the function calling convention and specifiers in all function definitions variants, I created two arrays of strings that contain default names for calling conventions and function specifiers. A macro determines these things by values in the arrays. So, if you define a new C macro for these names (sample: #define REGISTERCALL __fastcall), this macro will not work properly if you don't add this name in the necessary array. The default calling conventions (including my own and some Windows macros) and function specifiers are listed below:

Dim EnumCallConv() As String = { _
   "__fastcall", _
   "__cdecl", _
   "__stdcall", _
   "__thiscall", _
   "__clrcall", _
   "FASTCALL", _
   "CDECL", _
   "STDCALL", _
   "THISCALL", _
   "CLRCALL", _
   "PASCAL", _
   "WINAPI" _

Dim EnumSpecifiers() As String = { _
   "virtual", _
   "static", _
   "extern" _

Customizing Block Output Order

You can specify your own block output order. For this, you must modify one array of integers that must contain your order of blocks output. If you don't wan't use some block, you can simply not add a number of this block in the array. The number of each block is listed above. The default of block output order is:

Dim OutOrder() As Integer = _
{0, 1, 2, 3, 4, 6, 5, 0}

This means the next output order is as follows: Header, Function Name, Return Type, Calling convention, Specifier, Parameters list, Description, and Header. In addition, here are some macro work results:

// -=-=-=-=-=-=-=-=-=-=-=-=-=-
// Function [CreateButton]
// Return type [bool] -
// Calling convention [FASTCALL] -
// Parameters:
//    [HWND hp] -
//    [char *name] -
//    [pos_n x] -
//    [pos_n y] -
//    [size_n w] -
//    [size_n h] -
//    [DWORD dwStyle] -
//    [DWORD dwExStyle=0] -
//    [bool dovis=true] -
// Description:
// -=-=-=-=-=-=-=-=-=-=-=-=-=-
bool FASTCALL CreateButton(
   HWND hp,
   char *name,
   pos_n x,
   pos_n y,
   size_n w,
   size_n h,
   DWORD dwStyle,
   DWORD dwExStyle=0,
   bool dovis=true);

/* Description =
/* Function = FileOpen
/* Return type = e_FileError
/* Calling convention = FASTCALL
/* Parameters
/*   FILE * &f =
/*   const char *name =
/*   const char *mode =
e_FileError FASTCALL FileOpen(FILE * &f,const char *name, _
                              const char *mode);

// -=-=-=-=-=-=-=-=-=-=-=-=-=-
// Function [MsgHandler]
// Return type [LRESULT] -
// Specifier [virtual] -
// Parameters:
//   [UINT msg] -
//   [WPARAM wpar] -
//   [LPARAM lpar] -
// Description:
// -=-=-=-=-=-=-=-=-=-=-=-=-=-
virtual LRESULT MsgHandler(UINT msg,WPARAM wpar,LPARAM lpar);

Lines Commenting

The first macro, CommentLines, was made for commenting multiple lines of C/C++ code with aligning comments on the maximum selected line's length. I see an analog of this macro but without alignment, and they aren't compatible with Visual Studio 2005. The second macro, UncommentLines, can delete comments that have been created by the first macro. To add/delete comments, you need to select the needed text and execute the macro. Comments will be added/deleted to/from your code. This very simple and fast. Here is a sample of the results:


const LOGFONT sTrackBarDefRiskFont = {
   DEFAULT_PITCH, "Ms Serif"


const LOGFONT sTrackBarDefRiskFont = {
   15,7,                        //
   0,0,                         //
   FW_DONTCARE,0,0,0,           //
   DEFAULT_CHARSET,             //
   OUT_DEFAULT_PRECIS,          //
   CLIP_DEFAULT_PRECIS,         //
   DEFAULT_QUALITY,             //
   DEFAULT_PITCH, "Ms Serif"    //



  • Why is there a VB article in the C/C++ forum?

    Posted by mlgoff on 06/28/2006 10:05am

    This is obviously a VB .Net article. So why is it in the C/C++ forum?

    • why?

      Posted by acc15 on 06/29/2006 04:28am

      Expansion *.vb does not mean that this decision for VB .Net. Simple macro which you can insert into your macro project in VS 2005. Just use Ctrl+C, Ctrl+V.

Leave a Comment
  • Your email address will not be published. All fields are required.

Top White Papers and Webcasts

  • Bonita BPM 7 is here! And for you, an in-depth tour of its innovation. In this webinar, we'll guide you through the brand-new features of this release and demonstrate them live. You will: Discover how business application implementation and maintenance is now even easier, with decoupling of process logic, business data and user interface Learn how to create "living applications" for business processes which present business data in custom views We recommend that you watch the half-hour recording of our …

  • Intelligent N+X Redundancy, Placement Affinities, & Future Proofing in the Virtualized Data Center Virtualization brought about the ability to simplify business continuity management in IT. Workload portability and data replication capabilities mean that physical infrastructure failures no longer need impact application services, and they can rapidly be recovered even in the event of complete site failure. However, Enterprises and Service Providers face new challenges ensuring they have enough compute …

Most Popular Programming Stories

More for Developers

RSS Feeds

Thanks for your registration, follow us on our social networks to keep up-to-date