近段時間,一直在學習華爲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博客上的註釋模板;
一、文件註釋
二、函數註釋
/** * 讀取文件 * @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
View Code
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
View Code
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
View Code
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