利用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：

1. /*  
2.   *************************************************************  
3.   *                     Comments Add File  
4.   *             Copy Rights by BryanZhu @2010-2046  
5.   *  
6.   * FileName: BryanCommentsV1.0.em  
7.   * Author: BryanZhu  
8.   * Email: [e-mail]  
9.   * Date: 2010-08-29  
10.   *  
11.   *************************************************************  
12. */    
13.   
14. /*  
15.   *************************************************************  
16.   * FunctionName : GetStandardTimeString  
17.   * Description : get the system time by YYYY/MM/DD format.  
18.   * ReturnValue : return a system time string.  
19.   * Parameter[0] :  
20.   * Parameter[1] :   
21.   * Author : BryanZhu  
22.   * Date : 2010-08-29  
23.   *************************************************************  
24. */    
25. macro GetStandardTimeString()  
26. {  
27.     var szSysTime  
28.     var szYear  
29.     var szMonth  
30.     var szDay  
31.     var szTempMonth  
32.     var szTempDay  
33.     var szTimeString  
34.   
35.     szSysTime = GetSysTime(1)  
36.     szYear = szSysTime.Year  
37.     szTempMonth = szSysTime.Month  
38.     szTempDay = szSysTime.Day  
39.   
40.     if(szTempMonth < 10)  
41.     {  
42.         szMonth = "0@szTempMonth@"  
43.     }  
44.     else  
45.     {  
46.         szMonth = szTempMonth  
47.     }  
48.   
49.     if(szTempDay < 10)  
50.     {  
51.         szDay = "0@szTempDay@"  
52.     }  
53.     else  
54.     {  
55.         szDay = szTempDay  
56.     }  
57.       
58.     szTimeString = "@szYear@/@szMonth@/@szDay@"  
59.   
60.     return szTimeString  
61. }  
62.   
63.   
64. /*  
65.   *************************************************************  
66.   * FunctionName : InsertCommentsInfo  
67.   * Description : Save Basic Comments Info in a special file to parse the info.  
68.   *              by other macro functions.  
69.   * ReturnValue : NONE  
70.   * Parameter[0] :  
71.   * Parameter[1] :   
72.   * Author : BryanZhu  
73.   * Date : 2010-08-29  
74.   *************************************************************  
75. */   
76. macro InsertCommentsInfo(hbuf)  
77. {  
78.     var szModifyID  
79.     var szAuthorName  
80.     var szComment  
81.   
82.     szModifyID = "ModifyID:RF00000000"  
83.     szAuthorName = "AuthorName:BryanZhu"  
84.     szComment = "Comment:Please_input_your_comment_statement_here."  
85.   
86.     InsBufLine(hbuf, 0, szModifyID)  
87.     InsBufLine(hbuf, 1, szAuthorName)  
88.     InsBufLine(hbuf, 2, szComment)  
89. }  
90.   
91.   
92. /*  
93.   *************************************************************  
94.   * FunctionName : BryanSaveCommentsInfo  
95.   * Description : save the infomation of comments  
96.   * ReturnValue : NONE  
97.   * Parameter[0] :  
98.   * Parameter[1] :   
99.   * Author : BryanZhu  
100.   * Date : 2010-08-29  
101.   *************************************************************  
102. */    
103. macro BryanSaveCommentsInfo()  
104. {  
105.     var filename  
106.     var NewFileBufName  
107.     var hbuf  
108.     var hwnd  
109.   
110.     var hprj  
111.     var nProjFileCount  
112.     var iFileIndex  
113.     var tempFileName  
114.       
115.     filename = "CommentsConfigFile.bryan"  
116.   
117.     //judge the comments info file if is in current project.  
118.     hprj = GetCurrentProj()  
119.     nProjFileCount = GetProjFileCount(hprj)  
120.   
121.     iFileIndex = 0  
122.     while(iFileIndex < nProjFileCount)  
123.     {  
124.         tempFileName = GetProjFileName(hprj, iFileIndex)  
125.         if(tempFileName == filename)  
126.         {  
127.             //Msg("@filename@ file is existed in this project...")  
128.             hbuf = OpenBuf(filename)              
129.             if(hbuf != hNil)  
130.             {  
131.                 hwnd = NewWnd(hbuf)  
132.                 if(hwnd != hNil)  
133.                 {  
134.                     SaveBufAs(hbuf, filename)  
135.                     AddFileToProj(hprj, filename)  
136.                 }  
137.                 else  
138.                 {  
139.                     Msg("Create new window error!-1")  
140.                 }  
141.             }  
142.             else  
143.             {  
144.                 Msg("Create new empty file buffer error!-1")  
145.             }  
146.             break  
147.         }  
148.         else  
149.         {  
150.             iFileIndex = iFileIndex + 1  
151.             if(iFileIndex == nProjFileCount)  
152.             {  
153.                 //Msg("@filename@ file is not existed in this project...")  
154.                 hbuf = NewBuf(NewFileBufName)                 
155.                 if(hbuf != hNil)  
156.                 {  
157.                     hwnd = NewWnd(hbuf)  
158.                     if(hwnd != hNil)  
159.                     {  
160.                         hprj = GetCurrentProj()  
161.                         InsertCommentsInfo(hbuf)  
162.                         SaveBufAs(hbuf, filename)  
163.                         AddFileToProj(hprj, filename)  
164.                     }  
165.                     else  
166.                     {  
167.                         Msg("Create new window error!-2")  
168.                     }  
169.                     //CloseBuf(hbuf)  
170.                 }  
171.                 else  
172.                 {  
173.                     Msg("Create new empty file buffer error!-2")  
174.                 }                 
175.                 break  
176.             }  
177.         }  
178.     }  
179.     stop  
180. }  
181.   
182. macro GetCommentsInfoFileName()  
183. {  
184.     return "CommentsConfigFile.bryan"  
185. }  
186.   
187. macro IsCommentsInfoFileExist()  
188. {  
189.     var filename  
190.     var hprj  
191.     var nProjFileCount  
192.     var iFileIndex  
193.     var tempFileName  
194.       
195.     filename = "CommentsConfigFile.bryan"  
196.   
197.     hprj = GetCurrentProj()  
198.     nProjFileCount = GetProjFileCount(hprj)  
199.       
200.     iFileIndex = 0  
201.     while(iFileIndex < nProjFileCount)  
202.     {  
203.         tempFileName = GetProjFileName(hprj, iFileIndex)  
204.         if(tempFileName == filename)  
205.         {  
206.             return 1    // File is exist.  
207.         }  
208.         else  
209.         {  
210.             iFileIndex = iFileIndex + 1  
211.         }  
212.     }  
213.     return 0    // File is not exist.  
214. }  
215.   
216.   
217. macro GetCommentsInfo(iBufLineIndex)  
218. {  
219.     var filename  
220.     var hbuf  
221.     var szText  
222.     var nBufLineCount  
223.     var nTextLength  
224.   
225.     filename = GetCommentsInfoFileName()  
226.   
227.     if(IsCommentsInfoFileExist())  
228.     {  
229.         hbuf = OpenBuf(filename)  
230.         if(hbuf != hNil)  
231.         {  
232.             nBufLineCount = GetBufLineCount(hbuf)             
233.             if(iBufLineIndex <= nBufLineCount)  
234.             {  
235.                 szText = GetBufLine(hbuf, iBufLineIndex)  
236.                 nTextLength = strlen(szText)  
237.                 if(iBufLineIndex == 0)  
238.                 {  
239.                     szText = strmid(szText, 9, nTextLength)  
240.                 }  
241.                 else if(iBufLineIndex == 1)  
242.                 {  
243.                     szText = strmid(szText, 11, nTextLength)                  
244.                 }  
245.                 else if(iBufLineIndex == 2)  
246.                 {  
247.                     szText = strmid(szText, 8, nTextLength)               
248.                 }  
249.                 CloseBuf(hbuf)  
250.                 return szText     
251.             }  
252.             else  
253.             {  
254.                 Msg("GetCommentsInfo() parameter @iInfoIndex@ error....")  
255.             }  
256.         }  
257.         else  
258.         {  
259.             Msg("GetModifyIDofCommentsInfo(): Open buffer fail...")  
260.             stop  
261.         }         
262.     }  
263.     else  
264.     {  
265.         Msg("@filename@ is not exist...")  
266.         stop  
267.     }  
268. }  
269.   
270.   
271. /*  
272.   *************************************************************  
273.   * FunctionName : BryanAddSelBlockComments  
274.   * Description : add comments to contain the selected block statements.   
275.   * ReturnValue : NONE  
276.   * Parameter[0] :  
277.   * Parameter[1] :   
278.   * Author : BryanZhu  
279.   * Date : 2010-08-29  
280.   *************************************************************  
281. */    
282. macro BryanAddSelBlockComments()  
283. {  
284.     var hwnd  
285.     var hbuf  
286.     var firstSelLine  
287.     var lastSelLine  
288.       
289.     var sztempFirstRemark  
290.     var sztempLastRemark  
291.     var szFirstRemark  
292.     var szLastRemark  
293.     var szfirstSelLineText  
294.     var szTimeString  
295.   
296.     var szModifyID  
297.     var szAuthorName  
298.     var szComment  
299.     var ichIndex  
300.       
301.       
302.     sztempFirstRemark = "// <-"  
303.     sztempLastRemark  = "// ->"  
304.     szFirstRemark = Nil  
305.     szLastRemark = Nil  
306.     szTimeString = GetStandardTimeString()  
307.   
308.     szModifyID = GetCommentsInfo(0)  
309.     szAuthorName = GetCommentsInfo(1)  
310.     szComment = GetCommentsInfo(2)  
311.   
312.     if(IsCommentsInfoFileExist())  
313.     {  
314.         sztempFirstRemark = sztempFirstRemark # szModifyID # "-" # szAuthorName # "-" # szTimeString # "-" # szComment  
315.         sztempLastRemark  = sztempLastRemark  # szModifyID # "-" # szAuthorName  
316.         hwnd = GetCurrentWnd()  
317.         hbuf = GetCurrentBuf()  
318.         firstSelLine = GetWndSelLnFirst(hwnd)  
319.         lastSelLine = GetWndSelLnLast(hwnd)  
320.   
321.         szfirstSelLineText = GetBufLine(hbuf, firstSelLine)  
322.   
323.         ichIndex = 0  
324.         while(szfirstSelLineText[ichIndex] == "" || szfirstSelLineText[ichIndex] == "\t")  
325.         {  
326.             if(szfirstSelLineText[ichIndex] == "" )  
327.             {  
328.                 szFirstRemark = cat(szFirstRemark, "")  
329.                 szLastRemark = cat(szLastRemark, "")  
330.             }  
331.             else  
332.             {  
333.                 szFirstRemark = cat(szFirstRemark, "\t")  
334.                 szLastRemark = cat(szLastRemark, "\t")  
335.             }  
336.             ichIndex = ichIndex + 1  
337.         }  
338.           
339.         szFirstRemark = cat(szFirstRemark, sztempFirstRemark)  
340.         szLastRemark = cat(szLastRemark, sztempLastRemark)  
341.         InsBufLine(hbuf, firstSelLine, szFirstRemark)  
342.         InsBufLine(hbuf, lastSelLine+2, szLastRemark)  
343.   
344.         SaveBuf(hbuf)  
345.     }  
346.     else  
347.     {  
348.         BryanSaveCommentsInfo()  
349.     }  
350.   
351.     stop  
352. }  

三，添加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里的和左边两个自定义的宏，添加进去，点击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关联的用法，以后再做介绍。

原文转自：http://blog.csdn.net/bryantech/article/details/6876955
感谢 半童