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


Downloads

Comments

  • 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.

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

Top White Papers and Webcasts

  • On-demand Event Event Date: March 27, 2014 Teams need to deliver quality software faster and need integrated agile planning, task tracking, source control, auto deploy with continuous builds and a configurable process to adapt to the way you work. Rational Team Concert and DevOps Services (JazzHub) have everything you need to build great software, integrated seamlessly together right out of the box or available immediately in the cloud. And with the Rational Team Concert Client, you can connect your …

  • You probably have several goals for your patient portal of choice. Is "community" one of them? With a bevy of vendors offering portal solutions, it can be challenging for a hospital to know where to start. Fortunately, YourCareCommunity helps ease the decision-making process. Read this white paper to learn more. "3 Ways Clinicians can Leverage a Patient Portal to Craft a Healthcare Community" is a published document owned by www.medhost.com

Most Popular Programming Stories

More for Developers

Latest Developer Headlines

RSS Feeds