這應該是個過時的題目,相關的文件已經滿天飛了,不過最近程式寫得肥了,又是和其他人的合作項目,總不能老是這樣打開 Office Word 寫文件(掩面), 然後程式跟文件老是不同步,還是把註解改好用 doxygen 產生文件省事些,順帶得就寫個文章記錄一下。
doxygen 是一套文件產生程式,會自動 parse 原始碼、標頭檔等,搭配設定的模版,自動產生不同種類的文件,如 manpage, html , latex…。

要用 doxygen 第一步是先安裝 doxygen,這在 unix 下配上套件管理員應該跟喝水一樣簡單,略過不提。

doxygen -g <config-file> 產生設定檔,預設的名字會是 Doxyfile

下一步要編輯設定檔,我比較過預設設定,大概要改下面這些地方:

  • PROJECT_NAME:當然要改成自己的名字
  • OUTPUT_DIRECTORY:我設定在 doc 資料夾,並且把 doc 資料夾加到 .git 中
  • OUTPUT_LANGUAGE:設定語言
  • EXTRACT_ALL:設成 YES,這樣才會解析所有的檔案,否則預設只會解析 .h 檔,必須要用 \file 或 @file 定義過的檔案才會被解析
  • INPUT:用空白分隔的輸入檔案或資料夾,我是 src 資料夾
  • FILE_PATTERNS:設定要分析的檔案,這裡我只保留 .c 跟 .h
  • EXCLUDE:把不需要的資料夾剔掉,因為我有一個測試的 test 資料夾,所以把它加上去
  • GENERATE_*:設定要輸出的格式,我只選擇輸出 html ,設定 GENERATE_HTML 是 YES

為了在程式中加上更多資訊,可以在程式碼裡面為函式寫註解,我是使用下列的型式:

/*! * */

另外搭配以下幾個註解命令:

  • \brief 可以提供一行描述,簡短敘述這個函式的功能
  • \see 關鍵字,可以產生連結跳轉去其他的內容
  • \param 參數描述,有符合原始碼內的參數名稱,在排版上會自動上色並縮排
  • \return 對回傳值的描述

在 \brief 之後空一行,其它的內容則會歸為長敘述中,如果沒空行的話這些內容都會被濃縮成一行歸在 brief 裡面,所以,一個完整的函式註解如下:

/*!
 *
 * \brief dest = src xor dest
 *
 * do xor on src buffer and dest buffer, store result in dest buffer
 * \param src, dest buffer to xor
 * \param len buffer size both buffer should have enough space for len
 * \return none
 *
 */
int32_t xor2(
  uint8_t *src,
  uint8_t *dest,
  uint32_t len)

接著就可以下

doxygen config_file

產生文件,文件會在 doc/html 中
話說新一代的程式語言好像都自帶文件產生器,如 golang 的 godoc,rust 也有 rustdoc,也許 doxygen 這樣的東西,未來也用不太到了?