FeinSoftware presents CommentMakerPro ™ - comment generation tool designed to work in Visual C++ under current versions of Microsoft Visual Studio .NET 2002 (7.0), 2003 (7.1), 2005 (8.0)) and 2008 (9.0).
For a discussion about CommentMakerPro, other FeinSoftware's tools or Microsoft Visual Studio in general, please visit our new Forum.
Every developer understands the need of properly documenting their code, but not all of us do it.
Common reasons are "not enough time", "too many other things to do", etc.
CommentMakerPro does some of the work for you. It creates customizable comment blocks that you can adjust to your company’s documentation requirements.
For example, default settings of CommentMaker create comment blocks that are compatible with a popular document generation tool
Doxygen, which is used by many software companies.
There are many tools on the market similar to CommentMakerPro, but all of them have some shortcomings.
Most trivial simply paste a boilerplate for function header that must be edited according to number of function parameters, return type, etc.
Some are not compatible with Visual Studio .NET, other are simple text parsers that play a role of a C++ compiler to determine function's type, parameters, and parameters' type (often incorrectly).
The main difference of FeinSoftware's CommentMakerPro from its competitors is utilization of Visual Studio for the code analysis.
The comments generated by CommentMakerPro correctly list formal parameters of the function with their types, constness and optional default values.
For the function itself, CommentMakerPro states its access type (public, protected or private), whether it is virtual, constant, overloaded, constructor / destructor or operator.
CommentMakerPro is template-based, so it is fully customizable. It allows you to choose what information will be included in the generated comment: parameters, return type, remarks, reference, author and date, and to specify meta commands to use for each element.
This provides easy tuning to document generation tool of your choice, or simply to you company's standard.
New in version 1.1: Function comments could be inserted at either definition or declaration of that function. Version 1.1 also supports class comments (see description below).
New in version 1.2: One-click comment generation for entire file or entire project (see description below).
New in version 1.4: Generated comments are indented as their classes or functions.
New in version 1.5: New token for the Function Template $P_INOUT$ - inserts "[in]" or "[in, out]" for each function's parameter. Workaround for Visual Studio's incorrect behavior with nested classes and nested namespaces.
New in version 1.6: New conditional tokens and selection tokens were added to the comment templates (see description below). At this time, version 1.6 is only available for Visual Studio .NET 2003.
New in version 1.7: Comments for structures can now be generated (using "class" comment template). You can edit template files right from the "Options" dialog by clicking on one of the "Edit" buttons. Version 1.7 is available for Visual Studio .NET 2003 and 2005.
New in version 1.8: Added templates for comment blocks for variables and structures. Version 1.8 is available for Visual Studio .NET 2003 and 2005.
New in version 1.9: Minor bug fixes. Version 1.9 is available for Visual Studio .NET 2003 and 2005.
New in CommentMakerPro version 1.9.8: Special release for Visual Studio 2008.
CommentMakerPro ™ is designed to work in Microsoft Visual Studio .NET 2002, 2003, 2005 and 2008. Since CommentMakerPro is linked to the VC run-time library, FeinSoftware provides separate builds for these versions.
Please note that this is a fully functional version of CommentMakerPro ™.
The only difference is that it occasionally reminds you to register your copy.
Register CommentMakerPro ™ now for $20 via PayPal:
Your registration code and instructions will be e-mailed to you shortly after the payment is processed.
The FeinSoftware's CommentMakerPro comes in the standard msi installation package.
The first time you start your Visual Studio after installing CommentMakerPro, new "Comment Maker" submenu will be added to your "Tools" menu with the following commands:
The toolbar with these commands will also be created:
To insert a function header, simply position cursor anywhere in the function body and invoke "Insert Function Header" command either from the menu or from the toolbar.
The comment block will be inserted right in front of the function definition, after all existing comments.
The content of the function header is controlled by the Function Header Template file of the following format:
/// $F_ATRIB$ $F_NAME$
/// $<$ TODO: insert function description here $>$
/// @param $P_INOUT$ $P_NAME$ $P_TYPE$ $P_DEFAULT$ $FOR_EACH_PARAM_END$
/// @return $R_TYPE$ $IF_ELSE$
/// This function doesn't return a value
/// @remarks ///
/// @see ///
/// @author $AUTHOR$ @date $DATE$
The following tokens are defined for a function header template:
$F_NAME$ - function name
$F_ATRIB$ - function attributes (access type (public, protected or private), whether it is virtual, constant, overloaded, constructor / destructor or operator)
$R_TYPE$ - function return type
$AUTHOR$ - author's name
$DATE$ - current date (in the short locale-specific format)
$FOR_EACH_PARAM$ - beginning of the parameter list
$FOR_EACH_PARAM_END$ - end of the parameter list
(all text between these two tokens is repeated for each formal parameter)
$P_NAME$ - parameter name
$P_INOUT$ - [in] or [in, out] parameter
$P_TYPE$ - parameter type
$P_DEFAULT$ - parameter default value
$IF_PARAM$ - insert following text if the function takes any parameters
$IF_RETURN$ - insert following text if function returns any value
$IF_ELSE$ - "else" section for the conditional blocks
$IF_END$ - end conditional block
$<$ - beginning of the text selection (move cursor here for editing)
$>$ - end of the text selection (highlight selected text for editing)
To insert a file header, invoke "Insert File Header" command either from the menu or from the toolbar.
The comment block will be inserted in the beginning of your file.
The content of the file header is controlled by the File Header Template file of the following format: