代碼文檔生成工具Doxygen的使用備忘

Doxygen備忘

下載與安裝

通常步驟

• 生成配置文件Doxyfile: doxygen (-s) -g
• 創建目錄結構, 好比Doxyfile文件\doc文件夾(輸出)\src文件夾(放代碼) ->三者在同一目錄下
• 根據狀況設置配置文件中的參數(關鍵)
• 運行doxygen Doxyfile生成大概結構
• 針對每一個代碼文件寫doxygen註釋
• 繼續運行doxygen Doxyfile

配置文件Doxyfile設置

DOXYFILE_ENCODING      = UTF-8
PROJECT_NAME           = "Project Name"
PROJECT_NUMBER         = 1.0
PROJECT_BRIEF          = "This is a brief descript."
EXTRACT_ALL            = YES
OUTPUT_DIRECTORY       = "./doc"
OUTPUT_LANGUAGE        = Chinese
FULL_PATH_NAMES        = NO
WARN_LOGFILE           ="./doc/build.log"
INPUT                  ="./src"
FILE_PATTERNS          =
SOURCE_BROWSER         = NO
GENERATE_LATEX         = NO
CALL_GRAPH             = YES
CALLER_GRAPH           = YES
UML_LOOK               = YES
RECURSIVE              = YES

各類註釋規範

文件註釋

/**
    * Copyright (c) 2017, All rights reserverd.
    * 
    * @file $file$
    * @brief $brief$
    * Details.
    * 
    * @author  $author$,$email$
    * @date  $yy$-$mm$-$dd$
    * @version   $maj$.$min$
    *
    *************************************************/

命名空間

/**
    * @brief $brief$
    * Details.
    **/

結構體\枚舉

/** 
    * @brief $brief$
    * Details.
    **/

類註釋

/**
    * @brief $brief$
    * Details.
    **/

成員變量註釋

1. 在變量上面加
   /** 成員變量描述 */
2. 在變量後面加
   /**<成員變量描述 */

函數註釋

/** 
    * @brief $brief$-$test$
    * Details.
    * @param $param1$ : $param1_detail$
    * @param $param2$ : $param2_detail$
    * @return $return_detail$
    *        -<em>false</em> fail
    *        -<em>true</em>  succeed
    * @retval $return_note$
    * @deprecated $deprecated$
    * @see $see$
    * @pre $pre$
    **/

備註:

• note：指定函數注意項事或重要的註解指令操做符
  note格式以下：
  @note 簡要說明

• retval：指定函數返回值說明指令操做符。(注:更前面的return有點不一樣.這裏是返回值說明)
  retval格式以下：
  @retval 返回值 簡要說明

• pre：指定函數前置條件指令操做符
  pre格式以下：
  @pre 簡要說明

• par：指定擴展性說明指令操做符講。（它通常跟code、endcode一塊兒使用 ）
  par格式以下：
  @par 擴展名字

• code、endcode：指定
  code、endcode格式以下：
  @code
  簡要說明(內容)
  @endcode

• see：指定參考信息。
  see格式以下：
  @see 簡要參考內容

• deprecated：指定函數過期指令操做符。
  deprecated格式以下：
  @deprecated 簡要說明　
  調試Bug說明
  解決的bug說明，@bug
  警告說明 (warning)
  定義一些關於這個函數必須知道的事情，@warning
  備註說明 (remarks)
  定義一些關於這個函數的備註信息，@remarks
  將要完成的工做 (todo)
  說明哪些事情將在不久之後完成，@todo
  使用例子說明 (example)
  例子說明，@example example.cpp

關鍵字收集

@author          做者
@brief             摘要
@version         版本號
@date             日期
@file                文件名，能夠默認爲空，DoxyGen會本身加
@class             類名
@param           函數參數
@return           函數返回值描述
@exception      函數拋異常描述
@warning         函數使用中須要注意的地方
@remarks        備註
@see               see also字段
@note             brief下空一行後的內容表示詳細描述，但也能夠不空行用note表示
@par               開始一個段落，段落名稱描述由你本身指定，好比能夠寫一段示例代碼
@code             引用代碼段
@endcode        引用代碼段結束
@pre               函數前置條件，好比對輸入參數的要求
@post             函數後置條件，好比對系統狀態的影響或返回參數的結果預期


@param[in|out]     參數名及其解釋
@exception            用來講明異常類及拋出條件
@return                   對函數返回值作解釋
@note                      表示註解，暴露給源碼閱讀者的文檔
@remark                表示評論，暴露給客戶程序員的文檔
@since                   表示從那個版本起開始有了這個函數
@deprecated        引發不推薦使用的警告
@see                      表示交叉參考