what

doxygen是一個(gè)自動(dòng)根據(jù)注釋生成文檔的工具闪彼。支持html啼辣、chm、pdf等格式裙戏。

安裝

• 源碼
  github
• 編譯安裝
  工程使用cmake組織 乘凸。會(huì)缺少一些依賴，缺啥補(bǔ)啥就行累榜。

生成文檔的步驟

• 按照doxygen的規(guī)范進(jìn)行代碼注釋
• 生成一個(gè)配置文件营勤，根據(jù)自己的需要修改參數(shù)
• 調(diào)用doxygen生成文檔

實(shí)驗(yàn)1：生成doxygen的文檔。

• 準(zhǔn)備源碼
  doxygen的代碼本身就是按照自己的格式注釋的壹罚，這里不需要操作葛作。
• 生成配置文件
  -doxygen –g
• 生成不帶注釋的：doxygen -s –g
• 配置文件的修改參數(shù)
  參數(shù)都有注釋，可以簡單修改一下類似工程名猖凛、語言這些基本配置赂蠢，也可以不改。
• 進(jìn)入源碼目錄辨泳，執(zhí)行doxygen your-cfg-filename
  這就會(huì)生成一個(gè)html的文檔虱岂。
  
  image.png

這樣就會(huì)生成一份doxygen自己的文檔。

doxygen配置主要參數(shù)：

• PROJECT_NAME = “Test”
• PROJECT_NUMBER = 1.0.0
• OUTPUT_DIRECTORY = doc/
• OPTIMIZE_OUTPUT_FOR_C = NO
  c++這里就用NO
• TYPEDEF_HIDES_STRUCT = YES
  定義的結(jié)構(gòu)體菠红、枚舉第岖、聯(lián)合等數(shù)據(jù)類型，只按照 typedef定義的類型名進(jìn)行文檔化
• GENERATE_LATEX = NO
  默認(rèn)會(huì)生成一個(gè)html和latex的文檔试溯，有html就夠了蔑滓。
• RECURSIVE = YES
  是否遞歸調(diào)用
• GENERATE TREEVIEW ＝ ALL
  這會(huì)在HTML文檔中，添加一個(gè)側(cè)邊欄遇绞，并以樹狀結(jié)構(gòu)顯示包键袱、類、接口等的關(guān)系

注釋規(guī)范

• 單行注釋
  用“//!”來表示试读，例如：//!概要
• 多行注釋

/*!
xx@#$%~
xx^&*(
*/

• 各種標(biāo)記
  一些類似param杠纵、return這些標(biāo)記，doxygen會(huì)解釋這些標(biāo)記钩骇”仍澹可以用@鏈接這些標(biāo)記铝量，也可以用\
• b 加粗
• param 參數(shù)
• tparam 模板參數(shù)
• code和encode用于表示一個(gè)代碼塊

  SomeClass sc("hello");
  string result;
  int ret = sc.Func("world",3,result);
  \endcode

• note 說明注釋
• return 返回值
• todo 待做的
• deprecated 啟用的
• 使用@分組

//! @name operator
    //@{
        bool operator==(const SomeClass& other) const { return true;} 
        bool operator!=(const SomeClass& other) const { return true;} 
        bool operator<(const SomeClass& other) const { return true;} 
        bool operator>(const SomeClass& other) const { return true;} 
    //@}

完整的示例：

• 代碼：

#pragma once

/*! \file document.h */

#include <string>
#include <vector>

using namespace std;

//!概要
/*!
    具體注釋：

    \tparam 模板參數(shù)的注釋
    \see SomeClass::SomeClass

    這就是一個(gè)測(cè)試類。

    \b "\b"表示加粗
    \code 
    SomeClass sc("hello");
    string result;
    int ret = sc.Func("world",3,result);
    \endcode
*/
template<typename Type>
class SomeClass
{
public:
    /*!
        構(gòu)造函數(shù)

        \param str 輸入字符串

        \note 說明
    */
    SomeClass(string const& str){}

    //! 函數(shù)注釋概要
    /*!
        具體解釋
        \li 解釋1
        \li 解釋2
        \li 解釋3

        \param outStr 輸出字符串

        \return int 錯(cuò)誤碼,0表示成功

        \todo 對(duì)各種錯(cuò)誤進(jìn)行整理
    */
    int Func(string const& str,int len, string& outStr)
    {
        return 0;
    }

    //! \deprecated
    int Func()
    {
        return 0;
    }

    //! @name operator
    //@{
        bool operator==(const SomeClass& other) const { return true;} 
        bool operator!=(const SomeClass& other) const { return true;} 
        bool operator<(const SomeClass& other) const { return true;} 
        bool operator>(const SomeClass& other) const { return true;} 
    //@}
public:
    string value_;

private:
    int len_;
    Type type_;
}

• 生成的文檔如下：

  
  
  image.png
  
  
  image.png
  
  
  image.png