Auto-Commenting macro

Tired of documenting C++ functions? Me too. Just scroll, select, copy,
scroll, paste, delete parts, type text…

This little VB Script macro does half of the work for you. I don’t
have much to explain so — here’s the sample:

Initial state of C++ code:


BOOL CMainFrame::OnCmdMsg(UINT nID, int nCode, void* pExtra,
AFX_CMDHANDLERINFO* pHandlerInfo)
{
// let the view have first crack at the command
if (m_wndView.OnCmdMsg(nID, nCode, pExtra, pHandlerInfo))
return TRUE;

// otherwise, do default handling
return CFrameWnd::OnCmdMsg(nID, nCode, pExtra, pHandlerInfo);
}

And this is C++ code after starting CommentFunction() macro:


// ==================================================================
//
// FUNCTION : CMainFrame::OnCmdMsg()
//
// * Description :
//
//
// * Author : [Nenad Nikolic], Created : [10/31/98 7:11:41 PM]
//
// * Returns : [BOOL] –
//
// * Function parameters :
// [nID] –
// [nCode] –
// [pExtra] –
// [pHandlerInfo] –
//
// ==================================================================
BOOL CMainFrame::OnCmdMsg(UINT nID, int nCode, void* pExtra,
AFX_CMDHANDLERINFO* pHandlerInfo)
{
TRACE0( ” CMainFrame::OnCmdMsg() enteredn” );

// let the view have first crack at the command
if (m_wndView.OnCmdMsg(nID, nCode, pExtra, pHandlerInfo))
return TRUE;

// otherwise, do default handling
return CFrameWnd::OnCmdMsg(nID, nCode, pExtra, pHandlerInfo);
}

Inserted comment above the function is the result of CommentFunction() macro action. You need to select line(s) with function decleration and start the macro. In this case, select these two lines:


BOOL CMainFrame::OnCmdMsg(UINT nID, int nCode, void* pExtra,
AFX_CMDHANDLERINFO* pHandlerInfo)

As you can see, macro extracts pieces of function decleration and generates function comment with stuff that usually need to be commented. As a “bonus” you get “TRACE0” in first line of function body, for debugging purposes.

You can change authors name in code — simply replace rvalue of “author =” statement.

For information how to edit and start a macro, look at Visual Studio documentation.

Can be improved — suggestions are welcome.


‘ CODE (copy in your macro file)
‘——————————————————————————
Sub PrintText( s, newline )
ActiveDocument.Selection = s
if newline then
ActiveDocument.Selection.NewLine
end if
end sub

Function ParseParam( s )
Trim( s )
retpos = InStrRev( s, ” ” )
ParseParam = Right( s, len( s ) – retpos )
end function

‘ this is main function
Sub CommentFunction()

Dim win
set win = ActiveWindow

if win.type <> “Text” Then
MsgBox “This macro can only be run when a text editor window is active.”
else
fun = ActiveDocument.Selection.Text
if len(fun) = 0 then
exit sub
end if

retpos = InStr( 1, fun, ” “, vbTextCompare )
retval = Left( fun, retpos – 1)

lppos = InStr( 1, fun, “(“, vbTextCompare )
funcname = Mid( fun , retpos, lppos – retpos )

ActiveDocument.Selection.StartOfLine
ActiveDocument.Selection.LineUp
ActiveDocument.Selection.NewLine
PrintText “// ==================================================================”, TRUE
PrintText “// “, TRUE

PrintText “// FUNCTION : ” & funcname & “()”, TRUE
PrintText “// “, TRUE
PrintText “// * Description :”, TRUE
PrintText “// “, TRUE
PrintText “// “, TRUE

author = “Nenad Nikolic”
PrintText “// * Author : [” & author & “], Created : [” & CDate(Now) & “]”, TRUE
PrintText “// “, TRUE
PrintText “// * Returns : ” + “[” + retval + “] -“, TRUE
PrintText “// “, TRUE
PrintText “// * Function parameters : “, TRUE
fun = Right( fun, Len(fun) – lppos )
pos = 1

have_more = true
do while pos > 0 and have_more
pos = InStr( 1, fun, “,”, vbTextCompare )
if pos = 0 then
have_more = false
pos = InStr( 1, fun, “)”, vbTextCompare )
end if

if pos > 1 then
retval = Left( fun, pos – 1 )
retval = ParseParam( retval )
PrintText “// [” + retval + “] -“, TRUE
end if

if have_more = true then
fun = Right( fun, Len(fun) – pos )
end if
loop

PrintText “// “, TRUE
PrintText “// ==================================================================”, FALSE

‘ remove this part if you don’t want TRACE0
ActiveDocument.Selection.FindText “{”
ActiveDocument.Selection.CharRight
ActiveDocument.Selection.NewLine
PrintText “TRACE0( “”” & funcname & “() enteredn”” );”, TRUE

End If
end Sub

Date Last Updated: February 3, 1999

More by Author

Get the Free Newsletter!

Subscribe to Developer Insider for top news, trends & analysis

Must Read