KEIL/IAR 与 Doxygen 快速上手 - 嵌入式编程的注释管理小技巧

KEIL/IAR 与 Doxygen 快速上手 - 嵌入式编程的注释管理小技巧

在代码量较小时，一些朴素的注释习惯也许还能应付，但随着工程量增大，养成一些好的注释习惯并应用一定的工具，会大大提高代码的整体可读性。Keil和IAR是常用的嵌入式编程IDE，Doxygen是一个功能强大的代码文档生成软件，能够根据源代码的注释自动生成对应的文档。这里简单讲讲如何快速地利用Keil或者IAR的模板功能，写出有规范代码注释的代码，同时也简单介绍Doxygen如何在Keil和IAR工程原文件的基础上建立文档的主要步骤。

1.使用Keil的模板（Template）功能

Keil的提供一个模板功能，也就是一些常用的结构，如循环体和函数等，可以自动生成一个框架，然后具体的内容可以额外填写，十分方便。

使用模板

要使用模板功能，十分容易，在Keil中编辑状态下，如果Keil的视图和布局没有改变1，右边应该是工程文件的浏览界面。这个界面的右下角，可以点选模板（Template，图中第四个）栏：

就可以看到很多常用的C语言的一些程序结构，点击任意一个，就能在当前光标处插入对应的模板。

修改模板

Keil自带的模板大多都没有注释，如果要生成带注释版本的模板，就要自己修改或者添加新的模板。方法如下：

点选Edit菜单中的Configuration项；

即可在Configuration窗口里的Text Compilation栏，修改，增添或者删除模板了，添加符合Doxygen规范的注释即可。

例如比较常用的函数模板（void），一个符合Doxygen规范的模板是：

/** * @brief a short description of what the function does * @param the first input value * @return the return value * @details a full description of what the function does * @see a reference to another function */
void |(){
}

其中的”|“是模板生成后光标所在位置，上面的例子中生成模板后光标会在函数名处，可以直接输入新的函数名。

2.使用IAR的模板（Template）功能

IAR自然也有Keil的模板功能。

使用模板

在IAR中编辑状态下，在编辑栏里右键，并点击Insert Template，然后点选所需要的模板即可。IAR在这方面比Keil更好用一些，因为它会弹出一个对话框，往对话框里依次填入一些相应的初始化参数即可生成更为完整的代码段。

修改模板

从Insert Template菜单里可以看到，有Edit Templates一项，点选它就会进入一个名为CodeTemplates.ENU.txt 的编辑状态，这个就是IAR的模板文件。

这个模板文件的第一大段是由##包围的说明文件，如果想了解具体模板文件的设置可以参考这段文字。这里，我们可以在最后添加如下一段，以保证符合Doxygen规范的函数定义（和Keil的版本一致）：

#TEMPLATE &Doxygen>&Function,&brief=--,&param=--,&return=--,&details=--,&@see=--

/** * @brief %1 * @param %2 * @return %3 * @details %4 * @see %5 */
void(){
}

3.Doxygen快速上手

Doxygen是一个十分丰富和强大的工具，这里很难面面俱到地介绍它，关于它的注释规范，可以参考官方文档。

如果不用GraphViz生成调用图，那么一个最简单的生成文档的方法就是，把整个工程文件的路径交给Doxygen，然后简单配置项目名字，版本号等：

然后点选左边的Run栏，在一切配置正确的情况下，可以点击Run doxygen，然后等待执行完，可以点击左下角的Show Html即可用浏览器打开生成的文档。

4.小结

Doxygen其实可配置的空间十分大，这里只是简单介绍了一下如何快速生成文档。当然，文档是离不开好的注释习惯的，善用Keil/IAR的模板功能一定能够大大提升代码的可读性。

1. 如果想恢复到Keil原始的视图布局，点选Window菜单中的Reset View to Defaults项即可。 ↩