Doxygen給C程序生成註釋文檔

時間  2019-12-08
標籤 doxygen 程序 生成 註釋 文檔 欄目 C&C++ 简体版
原文   原文鏈接

　　 近段時間，一直在學習華爲C語言編程規範（2011版），在「註釋」這一章中發現了一種「Doxygen」的註釋轉文檔工具，查看諸多相關資料，並進行編程實踐，終於能夠利用Doxygen給C程序生成註釋文檔。在使用過程當中，我已經深深地喜歡Doxygen，並在寫代碼時使用Javadoc註釋風格。html

　　本文由三部分組成：1）工具下載及安裝；2）編寫Doxygen可識別的註釋；3）利用Doxygen工具將註釋轉換成API文檔。編程

　　一、工具下載及安裝瀏覽器

　　（1）Doxygen能夠從一套源文件開始，生成HTML格式的在線類瀏覽器。筆者採用的版本是Doxygen1.8.9.1
ide

　　（2）Microsoft HTML Help Workshop是微軟開發，用於本工程建立*.chm文件，筆者上官網下載最新的htmlhelp函數

　　（3）Graphviz用於配合doxygen使用，提取函數之間、頭文件之間的調用關係，筆者使用的版本是graphviz-2.38.工具

 

　　二、編寫Doxygen可識別的註釋學習

　　（1）註釋模板測試

　　本文采用的是Javadoc風格的註釋，參照CSDN博客上的註釋模板；url

　　1、文件註釋spa

/**
* @file  CommonType.h  
* @brief 常見類型定義
* @author       Vincent
* @date     2015-5-24 
* @version  A001 
* @copyright Vincent                                                              
*/

 

 

　　2、函數註釋

/** 
 * 讀取文件
 * @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);

 

　　3、類型/宏定義註釋

/**
* 2字節字符類型                                                                 
*/
typedef unsigned short WORD;

 

　　4、枚舉/結構註釋

/**  枚舉類型*/  
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
View Code

 

　　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;
}
View Code

 

　　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
View Code

 

　　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;
}
View Code

 

　　main.c

#include "DoxygenFile.h"
#include "CommonType.h"

/** 
* @mainpage    Doxygen工程演示
* @section    介紹
*            一、本工程使用了5個頭文件
* @ref    AddrDefine.h
* @ref    CommonType.h
* @ref    DoxygenFile.h
* @ref    HandleFile.h
* @ref    RetCode.h        \n
*            二、生成本工程，需安裝Doxygen、htmlhelp、GraphViz三個軟件                                                                     
*/

void main()
{
    HandleData(0,NULL,NULL);
}
View Code

 

　　三、利用Doxygen工具將註釋轉換成API文檔

　　接下來，就是利用Doxygen工具將DoxygenTest工程中註釋提取出來，轉換成chm格式的API文檔。第三部分分紅九步：一、工程配置；二、模式配置；三、輸出配置；四、調用圖配置；五、字符集配置；六、輸入字符集配置；七、chm配置；八、Grapviz配置；九、執行Doxygen。

　　一、工程配置；

　　

　　二、模式配置；

　　

　　三、輸出配置；

　　

　　四、調用圖配置；

　　

　　五、字符集配置；

　　

　　六、輸入字符集配置；

　　

　　七、chm配置；

　　

　　八、Grapviz配置；

　　

　　九、執行Doxygen

　　

　　

　　完成上述操做以後，就能生成以下API文檔

　　

　　參考資料

　　一、Doxygen配置以及註釋詳細說明文檔：doxygen_manual-1.8.9.1.pdf

　　二、C++ 程序文檔生成器介紹(doxygen)

　　三、使用doxygen生成chm範例

　　四、嵌入式C語言中的Doxygen註釋模板

　　五、Doxygen使用簡介

相關文章
相關標籤/搜索
每日一句
    每一个你不满意的现在，都有一个你没有努力的曾经。
本站公眾號
   歡迎關注本站公眾號,獲取更多信息
聯繫我們 最近搜索 最新文章 沪ICP备13005482号-10 MyBatis教程 SQL 教程 MySQL教程 Java 教程 Thymeleaf 教程 Hibernate教程 Spring教程 Redis教程