近段時間，一直在學習華為C語言編程規范（2011版），在“注釋”這一章中發現了一種“Doxygen”的注釋轉文檔工具，查看諸多相關資料，並進行編程實踐，終於可以利用Doxygen給C程序生成注釋文檔。在使用過程中，我已經深深地喜歡Doxygen，並在寫代碼時使用Javadoc注釋風格。
本文由三部分組成：1）工具下載及安裝；2）編寫Doxygen可識別的注釋；3）利用Doxygen工具將注釋轉換成API文檔。
1、工具下載及安裝
（1）Doxygen可以從一套源文件開始，生成HTML格式的在線類瀏覽器。筆者采用的版本是Doxygen1.8.9.1
（2）Microsoft HTML Help Workshop是微軟開發，用於本工程創建*.chm文件，筆者上官網下載最新的htmlhelp
（3）Graphviz用於配合doxygen使用，提取函數之間、頭文件之間的調用關系，筆者使用的版本是graphviz-2.38.
2、編寫Doxygen可識別的注釋
（1）注釋模板
本文采用的是Javadoc風格的注釋，參照CSDN博客上的注釋模板；
一、文件注釋
/** * @file CommonType.h * @brief 常見類型定義 * @author Vincent * @date 2015-5-24 * @version A001 * @copyright Vincent */
二、函數注釋
/** * 讀取文件 * @param[in] fileNameLen 文件名長度 * @param[in] fileName 文件名 * @param[in] dataLen 數據長度 * @param[out] fileData 輸出數據 * @return 0，執行成功，非0，失敗，詳見 * @ref RetCode.h * @see * @note */ UINT ReadFile(UINT fileNameLen, BYTE *fileName, UINT dataLen, BYTE *fileData);
三、類型/宏定義注釋
/** * 2字節字符類型 */ typedef unsigned short WORD;
四、枚舉/結構注釋
/** 枚舉類型*/ enum COLOR{ RED=0, ///< 紅色 GREEN=1,///< 綠色 YELLOW=2///< 黃色 };
（2）Doxygen工程實例
為了讓接觸Doxygen工具的人快速上手，筆者使用VC++6.0創建了一個DoxygenTest工程，並為其編寫測試代碼以及Javadoc風格的注釋，工程的文件列表如下圖所示，並依次展示每個文件的代碼。
AddrDefine.h
/** * @file AddrDefine.h * @brief 地址定義 */ #ifndef ADDR_DEFINE_H #define ADDR_DEFINE_H /**@name 地址定義 * @{ */ #define ADDR_FILE_START 0x00000000 ///<文件起始地址 #define ADDR_DIR_START 0x00000001 ///<目錄起始地址 /**@} */ #endif
CommonType.h
/** * @file CommonType.h * @brief 常見類型定義 * @author Vincent * @date 2015-5-24 * @version A001 * @copyright Vincent */ #ifndef COMMON_TYPE_H #define COMMON_TYPE_H /** * 4字節字符類型 */ typedef unsigned int UINT; /** * 1字節字符類型 */ typedef unsigned char BYTE; /** * 2字節字符類型 */ typedef unsigned short WORD; /** 坐標系類型 */ typedef struct{ int x;///<橫坐標 int y;///<縱坐標 }Coordinator; /** 枚舉類型*/ enum COLOR{ RED=0, ///< 紅色 GREEN=1,///< 綠色 YELLOW=2///< 黃色 }; /** 空的宏定義*/ #define NULL 0 #endif
RetCode.h
/** * @file RetCode.h * @brief 錯誤碼返回值 * @author Vincent * @date 2015-5-24 * @version A001 * @par Copyright (c): Vincent */ #ifndef RET_CODE_H #define RET_CODE_H /**@name 執行狀態 * @{ */ #define SUCCESS 0x00000000 ///<執行成功 #define ERR_PARA_LEN 0x00000001 ///<長度錯誤 #define ERR_NULL_POINT 0x00000002 ///<空指針錯誤 #define ERR_PARA_TYPE 0x00000003 ///<參數類型錯誤 /** @}*/ #endif
DoxygenFile.h
/** * @file DoxygenFile.h * @brief 中間層，用於處理數據 * @author Vincent * @date 2015-5-24 * @version A001 * @par Copyright (c): Vincent */ #ifndef DOXYGEN_FILE_H #define DOXYGEN_FILE_H #include "CommonType.h" /** * 寫入一些內容 * @param[in] fileNameLen 文件名長度 * @param[in] fileName 文件名 * @param[out] fileData 文件數據 * @return 0，執行成功，非0，失敗，詳見 * @ref RetCode.h */ int HandleData(UINT fileNameLen,BYTE *fileName, BYTE *fileData); #endif
DoxygenFile.c
#include "DoxygenFile.h" #include "HandleFile.h" /** * 寫入一些內容 * @param[in] fileNameLen 文件名長度 * @param[in] fileName 文件名 * @param[out] fileData 文件數據 * @return 0，執行成功，非0，失敗，詳見 * @ref RetCode.h */ int HandleData(UINT fileNameLen,BYTE *fileName, BYTE *fileData) { UINT retCode; retCode = ReadFile(0,NULL,0,NULL); return retCode; }
HandleFile.h
/** * @file HandleFile.h * @brief 操作文件 * @details 所有涉及文件操作 * @author Vincent * @date 2015-5-24 * @version A001 * @par Copyright (c): Vincent */ #ifndef HANDLE_FILE_H #define HANDLE_FILE_H #include "CommonType.h" /** * 讀取文件 * @param[in] fileNameLen 文件名長度 * @param[in] fileName 文件名 * @param[in] dataLen 數據長度 * @param[out] fileData 輸出數據 * @return 0，執行成功，非0，失敗，詳見 * @ref RetCode.h * @see * @note */ UINT ReadFile(UINT fileNameLen, BYTE *fileName, UINT dataLen, BYTE *fileData); /** * 寫入文件 * @param[in] fileNameLen 文件名長度 * @param[in] fileName 文件名 * @param[out] fileData 輸出數據 * @return 0，執行成功，非0，失敗，詳見 * @ref RetCode.h * @see * @note */ UINT WriteFile(UINT fileNameLen, BYTE *fileName, BYTE *fileData); /** * 擦除文件 * @param[in] fileNameLen 文件名長度 * @param[in] fileName 文件名 * @return 0，執行成功，非0，失敗，詳見 * @ref RetCode.h * @see * @note */ UINT EraseFile(UINT fileNameLen, BYTE *fileName); #endif
HandleFile.c
#include "HandleFile.h" #include "RetCode.h" #include "AddrDefine.h" /** * 讀取文件 * @param[in] fileNameLen 文件名長度 * @param[in] fileName 文件名 * @param[in] dataLen 數據長度 * @param[out] fileData 輸出數據 * @return 0，執行成功，非0，失敗，詳見 * @ref RetCode.h * @see * @note */ UINT ReadFile(UINT fileNameLen, BYTE *fileName, UINT dataLen, BYTE *fileData) { return SUCCESS; } /** * 寫入文件 * @param[in] fileNameLen 文件名長度 * @param[in] fileName 文件名 * @param[out] fileData 輸出數據 * @return 0，執行成功，非0，失敗，詳見 * @ref RetCode.h * @see * @note */ UINT WriteFile(UINT fileNameLen, BYTE *fileName, BYTE *fileData) { return SUCCESS; } /** * 擦除文件 * @param[in] fileNameLen 文件名長度 * @param[in] fileName 文件名 * @return 0，執行成功，非0，失敗，詳見 * @ref RetCode.h * @see * @note */ UINT EraseFile(UINT fileNameLen, BYTE *fileName) { return SUCCESS; }
main.c
#include "DoxygenFile.h" #include "CommonType.h" /** * @mainpage Doxygen工程演示 * @section 介紹 * 1、本工程使用了5個頭文件 * @ref AddrDefine.h * @ref CommonType.h * @ref DoxygenFile.h * @ref HandleFile.h * @ref RetCode.h \n * 2、生成本工程，需安裝Doxygen、htmlhelp、GraphViz三個軟件 */ void main() { HandleData(0,NULL,NULL); }
3、利用Doxygen工具將注釋轉換成API文檔
接下來，就是利用Doxygen工具將DoxygenTest工程中注釋提取出來，轉換成chm格式的API文檔。第三部分分成九步：1、工程配置；2、模式配置；3、輸出配置；4、調用圖配置；5、字符集配置；6、輸入字符集配置；7、chm配置；8、Grapviz配置；9、執行Doxygen。
1、工程配置；
2、模式配置；
3、輸出配置；
4、調用圖配置；
5、字符集配置；
6、輸入字符集配置；
7、chm配置；
8、Grapviz配置；
9、執行Doxygen
完成上述操作之后，就能生成如下API文檔
參考資料
1、Doxygen配置以及注釋詳細說明文檔：doxygen_manual-1.8.9.1.pdf