doxygen簡單介紹,一篇入門

doxygen簡單介紹

1. 概述

   doxygen官方文檔

   這是一個生成文檔的工具,能夠經過代碼文件中的註釋進行文檔的生成,經過畫圖工具能夠繪製調用過程和文件包含關係等

2. 安裝

   sudo apt-get install doxygen doxygen-gui

   doxygen-gui是一個能夠經過圖形界面生成配置文件的工具

3. 使用

   只要在代碼註釋中作了特殊的標記,就使用這個工具進行文檔的生成

   過程以下(詳細配置之後再說)

   1. mkdir doc;cd doc

   2. doxygen -g ;#生成一個配置文件名字爲Doxyfile

   3. 打開Doxyfile,修改裏面的配置(粗體是使用的配置)

      GENERATE_LATEX = YES| NO #這個是配置是否是生成latex(pdf)

      DISABLE_INDEX = YES | NO #索引是否是有,可能影響搜索功能

      GENERATE_TREEVIEW = YES | NO #是否是生成右側的樹型索引

      EXTRACT_ALL = YES | NO #這個配置生成文檔的大小,咱們向讓它詳細,就配置YES

      INPUT = ../ #這個配置輸入的文件目錄,源文件在那個目錄下.

   4. 執行 doxygen Doxygen 就能生成一個html目錄,裏面有生成的文檔.

4. 使用doxygen時的註釋應該如何寫

   註解官方文檔 doxygen Sepcial Command

   註解

   通常來講,註釋都是說明的後面代碼的,若是想讓註釋說明前面的代碼,可使用在註明寫入doxygen文檔的標記後緊跟一個< 來講明,好比作結構體或者成員變量的註釋的時候,注意,寫在後面的註解只能指明註解說明的是前 一 行的內容

   在註釋後在寫一個前一個字符就是告訴doxygen這個註釋就是要寫入文檔的, 好比

   C // 是普通註釋,///就是寫入doxygen 文檔的註釋了, /* */ 是普通註釋, /** */ 就是寫入doxygen文檔的註釋了,

   PYTHON 中 # 是普通註釋, ## 就是寫入doxygen文檔的註釋了.

5. 註釋中經常使用的標記

   注意 通常來講,詳細的描述都是在\brief後面空一行開始的,若是不空一行,都會即便換行了也會認爲是brief的內容的 多餘的空行doxygen都會認爲是空一行的, 空一行的解釋 空一行不僅是一個 \n ,是在一行內,只有 doxygen識別出寫入文檔的標記 以前的內容,以下所示:

   /**         (這裏是標記開始寫入doxygen庫)
    * \brief   (這裏標記這是一個簡要說明)
    *          (這裏是空行的樣式)
    *          (這裏若是有信息,就認爲是詳細註釋的內容)
    *          (多餘的空行doxygen會認爲只有一個空行)
    */

   使用 \xxxx 或者 @xxx 標識一個標記,標記會讓doxygen特殊處理後面的註釋.

   經常使用

   \brief 簡短說明,這個會在概述部分出現的說明,旁邊會有一個more按鈕,點擊查看詳情,

   \param 參數說明,作在函數前面是說明每一個參數的做用,doxygen會作特殊處理,換個顏色

   \return 說明一個函數的返回值

   \retval 說明返回值類型

   說明類標記

   \note 這個是說明部分,doxygen會起一個 Note 或者 說明 段落進行說明 這個標籤以後的註釋內容

   \attention 注意

   \warning 警告信息

   \exception 可能產生的異常描述

   會產生鏈接的標記

   \see 後面加一個class名稱或者function名稱,doxygen會生成一個指向這個函數詳細說明的鏈接

   \enum [MY_ENUM|CTest::Enum] 後面加一個枚舉,

   \var [Variable] 引用某個變量

   \class 引用某個類

   下面是給文件註釋的時候經常使用的標記,通常用在文件的開頭

   \file 文件名(這個通常寫文件的文件名稱,在文件裏看到本文件的文件名稱,不要寫別的,註釋規範,具體爲啥我也不知道啊)

   \brief 這個和對函數和類的註釋的含義是同樣的,對一個文件的簡單註釋

   \author 說明這個文件的做者

   \version [1.1] 版權聲明

   \date 文件的建立日期

6. 結構體或者類成員變量的說明

   沒有這類特殊標記的,doxygen會分析代碼的結構,咱們只要在對應的變量前面或者 統一行的後面(使用<) 作寫入doxygen 文檔的標記就好了.

7. 有關doxygen生成圖表的配置.

   準備工做:

   sudo apt-get install graphvize doxygen doxygen-gui

   配置步驟:

   1. 運行 doxywizard
   2. 文件打開一個使用doxygen -g 生成的配置文件

   3. 在 Wizard => Mode 下配置 All Entities 和 Include cross-referenced source code in the output ,在下面選擇一個

      針對語言的優化選項

   4. 在 Wizard => Output 下配置輸出格式,
   5. 生成圖表這一步是關鍵 在 Wizard => Diagrams 下配置生成的圖表類型勾選 Call graphs 和 Called by graphs 等等,就會生成對應圖表
   6. 在 Export => Project 下選擇輸出語言 這個語言是值doxygen的網也框架的語言,選英文也是能夠輸出中文註釋的,
   7. 生成圖表這一步是關鍵 在 Export => Dot 下勾選 CALL_GRAPH CALLER_GRAPH 等,配置DOT_PATH (通常配置爲/usr/bin)
   8. 在 Run 下點擊 Run doxygen 開始生成文檔,關閉的時候會提示是否保存,點擊保存,之後就可使用doxygen生成了.