利用Source Insight宏语言脚本添加注释

一，前言

    总所周知，在Windows开发环境中，一个几百兆C语言工程代码中，最好用的编辑工具当然就是Source Insight了。Source Insight(目前大多使用的版本为3.5)的Macro Language提供的API非常强大，其实我们可以利用这些API编写一些脚本，通过映射快捷键来达到高效而规范开发的目的。

    而在一个团队协作开发的项目中，如果后期主要工作是Debug，那么仅仅只是规范注释，对于问题的追踪，代码的美观都显得尤为重要。因为Source Insight可以自定义出各种功能的脚本。本文只介绍如何利用Source Insight的宏语言编写脚本，快速添加统一规范化的注释。

二，编写注释脚本

    打开Source Insight，按F1，会出来Source Insight Help文档，里面有个Macro Language Guide，相信大家看完之后，都可以尝试着去编写各种各样的脚本出来。正如Vim出来之后，很多牛人编写了功能强大的插件一样，让Vim成为Linux下的一件编辑利器。本人也是通过尝试，花了一个晚上时间写出来一个添加注释的简单脚本。在此贴出我的脚本，文件名为 BryanCommentsV1.0.em：

/*
  *************************************************************
  *						Comments Add File
  *				Copy Rights by BryanZhu @2010-2046
  *
  * FileName: BryanCommentsV1.0.em
  * Author: BryanZhu
  * Email: hbzqiang@163.com
  * Date: 2010-08-29
  *
  *************************************************************
*/  

/*
  *************************************************************
  * FunctionName : GetStandardTimeString
  * Description : get the system time by YYYY/MM/DD format.
  * ReturnValue : return a system time string.
  * Parameter[0] :
  * Parameter[1] : 
  * Author : BryanZhu
  * Date : 2010-08-29
  *************************************************************
*/  
macro GetStandardTimeString()
{
	var szSysTime
	var szYear
	var szMonth
	var szDay
	var szTempMonth
	var szTempDay
	var szTimeString

	szSysTime = GetSysTime(1)
	szYear = szSysTime.Year
	szTempMonth = szSysTime.Month
	szTempDay = szSysTime.Day

	if(szTempMonth < 10)
	{
		szMonth = "0@szTempMonth@"
	}
	else
	{
		szMonth = szTempMonth
	}

	if(szTempDay < 10)
	{
		szDay = "0@szTempDay@"
	}
	else
	{
		szDay = szTempDay
	}
	
	szTimeString = "@szYear@/@szMonth@/@szDay@"

	return szTimeString
}


/*
  *************************************************************
  * FunctionName : InsertCommentsInfo
  * Description : Save Basic Comments Info in a special file to parse the info.
  *			     by other macro functions.
  * ReturnValue : NONE
  * Parameter[0] :
  * Parameter[1] : 
  * Author : BryanZhu
  * Date : 2010-08-29
  *************************************************************
*/ 
macro InsertCommentsInfo(hbuf)
{
	var szModifyID
	var szAuthorName
	var szComment

	szModifyID = "ModifyID:RF00000000"
	szAuthorName = "AuthorName:BryanZhu"
	szComment = "Comment:Please_input_your_comment_statement_here."

	InsBufLine(hbuf, 0, szModifyID)
	InsBufLine(hbuf, 1, szAuthorName)
	InsBufLine(hbuf, 2, szComment)
}


/*
  *************************************************************
  * FunctionName : BryanSaveCommentsInfo
  * Description : save the infomation of comments
  * ReturnValue : NONE
  * Parameter[0] :
  * Parameter[1] : 
  * Author : BryanZhu
  * Date : 2010-08-29
  *************************************************************
*/  
macro BryanSaveCommentsInfo()
{
	var filename
	var NewFileBufName
	var hbuf
	var hwnd

	var hprj
	var nProjFileCount
	var iFileIndex
	var tempFileName
	
	filename = "CommentsConfigFile.bryan"

	//judge the comments info file if is in current project.
	hprj = GetCurrentProj()
	nProjFileCount = GetProjFileCount(hprj)

	iFileIndex = 0
	while(iFileIndex < nProjFileCount)
	{
		tempFileName = GetProjFileName(hprj, iFileIndex)
		if(tempFileName == filename)
		{
			//Msg("@filename@ file is existed in this project...")
			hbuf = OpenBuf(filename)			
			if(hbuf != hNil)
			{
				hwnd = NewWnd(hbuf)
				if(hwnd != hNil)
				{
					SaveBufAs(hbuf, filename)
					AddFileToProj(hprj, filename)
				}
				else
				{
					Msg("Create new window error!-1")
				}
			}
			else
			{
				Msg("Create new empty file buffer error!-1")
			}
			break
		}
		else
		{
			iFileIndex = iFileIndex + 1
			if(iFileIndex == nProjFileCount)
			{
				//Msg("@filename@ file is not existed in this project...")
				hbuf = NewBuf(NewFileBufName)				
				if(hbuf != hNil)
				{
					hwnd = NewWnd(hbuf)
					if(hwnd != hNil)
					{
						hprj = GetCurrentProj()
						InsertCommentsInfo(hbuf)
						SaveBufAs(hbuf, filename)
						AddFileToProj(hprj, filename)
					}
					else
					{
						Msg("Create new window error!-2")
					}
					//CloseBuf(hbuf)
				}
				else
				{
					Msg("Create new empty file buffer error!-2")
				}				
				break
			}
		}
	}
	stop
}

macro GetCommentsInfoFileName()
{
	return "CommentsConfigFile.bryan"
}

macro IsCommentsInfoFileExist()
{
	var filename
	var hprj
	var nProjFileCount
	var iFileIndex
	var tempFileName
	
	filename = "CommentsConfigFile.bryan"

	hprj = GetCurrentProj()
	nProjFileCount = GetProjFileCount(hprj)
	
	iFileIndex = 0
	while(iFileIndex < nProjFileCount)
	{
		tempFileName = GetProjFileName(hprj, iFileIndex)
		if(tempFileName == filename)
		{
			return 1 	// File is exist.
		}
		else
		{
			iFileIndex = iFileIndex + 1
		}
	}
	return 0	// File is not exist.
}


macro GetCommentsInfo(iBufLineIndex)
{
	var filename
	var hbuf
	var szText
	var nBufLineCount
	var nTextLength

	filename = GetCommentsInfoFileName()

	if(IsCommentsInfoFileExist())
	{
		hbuf = OpenBuf(filename)
		if(hbuf != hNil)
		{
			nBufLineCount = GetBufLineCount(hbuf)			
			if(iBufLineIndex <= nBufLineCount)
			{
				szText = GetBufLine(hbuf, iBufLineIndex)
				nTextLength = strlen(szText)
				if(iBufLineIndex == 0)
				{
					szText = strmid(szText, 9, nTextLength)
				}
				else if(iBufLineIndex == 1)
				{
					szText = strmid(szText, 11, nTextLength)				
				}
				else if(iBufLineIndex == 2)
				{
					szText = strmid(szText, 8, nTextLength)				
				}
				CloseBuf(hbuf)
				return szText	
			}
			else
			{
				Msg("GetCommentsInfo() parameter @iInfoIndex@ error....")
			}
		}
		else
		{
			Msg("GetModifyIDofCommentsInfo(): Open buffer fail...")
			stop
		}		
	}
	else
	{
		Msg("@filename@ is not exist...")
		stop
	}
}


/*
  *************************************************************
  * FunctionName : BryanAddSelBlockComments
  * Description : add comments to contain the selected block statements. 
  * ReturnValue : NONE
  * Parameter[0] :
  * Parameter[1] : 
  * Author : BryanZhu
  * Date : 2010-08-29
  *************************************************************
*/  
macro BryanAddSelBlockComments()
{
	var hwnd
	var hbuf
	var firstSelLine
	var lastSelLine
	
	var sztempFirstRemark
	var sztempLastRemark
	var szFirstRemark
	var szLastRemark
	var szfirstSelLineText
	var szTimeString

	var szModifyID
	var szAuthorName
	var szComment
	var ichIndex
	
	
	sztempFirstRemark = "// <-"
	sztempLastRemark  = "// ->"
	szFirstRemark = Nil
	szLastRemark = Nil
	szTimeString = GetStandardTimeString()

	szModifyID = GetCommentsInfo(0)
	szAuthorName = GetCommentsInfo(1)
	szComment = GetCommentsInfo(2)

	if(IsCommentsInfoFileExist())
	{
		sztempFirstRemark = sztempFirstRemark # szModifyID # "-" # szAuthorName # "-" # szTimeString # "-" # szComment
		sztempLastRemark  = sztempLastRemark  # szModifyID # "-" # szAuthorName
		hwnd = GetCurrentWnd()
		hbuf = GetCurrentBuf()
		firstSelLine = GetWndSelLnFirst(hwnd)
		lastSelLine = GetWndSelLnLast(hwnd)

		szfirstSelLineText = GetBufLine(hbuf, firstSelLine)

		ichIndex = 0
		while(szfirstSelLineText[ichIndex] == "" || szfirstSelLineText[ichIndex] == "\t")
		{
			if(szfirstSelLineText[ichIndex] == "" )
			{
				szFirstRemark = cat(szFirstRemark, "")
				szLastRemark = cat(szLastRemark, "")
			}
			else
			{
				szFirstRemark = cat(szFirstRemark, "\t")
				szLastRemark = cat(szLastRemark, "\t")
			}
			ichIndex = ichIndex + 1
		}
		
		szFirstRemark = cat(szFirstRemark, sztempFirstRemark)
		szLastRemark = cat(szLastRemark, sztempLastRemark)
		InsBufLine(hbuf, firstSelLine, szFirstRemark)
		InsBufLine(hbuf, lastSelLine+2, szLastRemark)

		SaveBuf(hbuf)
	}
	else
	{
		BryanSaveCommentsInfo()
	}

	stop
}

三，添加BryanCommentsV1.0.em脚本到Source Insight的Base项目中

    将BryanCommentsV1.0.em拷贝到Source Insight的Base项目所在的文件夹下，比如 C:\Documents and Settings\Source Insight\Projects\Base    ，然后打开Source Insight的Base项目，通过菜单Project -> Add and Remove Project Files... ，将BryanCommentsV1.0.em添加进Base项目。

四，自定义菜单

    打开Menu -> Menu Assignments， Menu栏选择Work菜单(当然，你想把自定义的Macro功能添加到哪个菜单都行。笔者以Work菜单为例) ，在Command栏输入macro快速查找，这时会出现Macro: BryanAddSelBlockComments和Macro: BryanSaveCommentsInfo两个在脚本里自定义的宏，选中Menu Contents里的<end of menu>和左边两个自定义的宏，添加进去，点击OK，即可。

五，编辑注释信息

    在Work菜单中，点击BryanSaveCommentsInfo，这时可以编辑ModifyID，这个ID可以是你的BUG库ID，可以编辑AuthorName为自己的姓名，可以编辑Comment注释信息，编辑之后保存即可。在点击BryanSaveCommentsInfo的那一刻，脚本生成了一份CommentsConfigFile.bryan注释配置文件并添加进你所在的工程，这个文件保存着你的注释配置信息。如图1所示。

图1

六，添加注释

    这时可以在代码中选中某个模块，或者函数，或者语句块，如图2所示，点击BryanAddSelBlockComments，则注释就添加进去了，如图3所示。在注释中，可以通过搜索BUG ID，直接追踪你修改的所有代码，也可以通过姓名搜索追踪你修改的所有功能。不仅方便查询，而且注释格式风格一样，一目了然，便于阅读，利于代码规范。

图2

图3

七，结语：

    大家有兴趣，可以自定义各种各样有利于代码规范和提供工作效率的脚本。关于Source Insight和VC6.0，Visual Studio2008关联的用法，以后再做介绍。

  半童

2011.10.15北京

Email: hbzqiang@163.com