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:

Before:

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"
};

After:

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"    //
};