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項即可。 ↩