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() entered\n" );

	// 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 & "() entered\n"" );", TRUE

 End If
end Sub

Date Last Updated: February 3, 1999



Comments

  • There are no comments yet. Be the first to comment!

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

Top White Papers and Webcasts

  • What does it take to win? According to Jack Welch, winning in business is great because when companies win, people thrive and grow. However, it goes without saying that you have to win the right way -- cleanly and by the rules. Even the most talented businessperson with the best intentions will get nowhere unless he or she knows how to win in today's complex business world. Read this book summary to learn not only the strategies of winning, but also the value that those strategies bring to your professional …

  • Cloud computing isn't new, but it's still a hot topic in technology circles. Moving to the cloud has done great things for many businesses. When it comes to handling a basic business necessity, cloud computing has brought many improvements to overall business continuity. Using the cloud for DR makes a lot of sense for many, but it's not exactly the most simple concept. Read this eBook to find answers to all the key questions IT professionals have about cloud-based disaster recovery, and helpful info around the …

Most Popular Programming Stories

More for Developers

RSS Feeds

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