Doxygen 程式文件產生器 與 簡易筆記

Doxygen 是一套程式文件的產生器, 會抓取程式的內容、註解來自動產生程式說明文件的系統.

下述內容太多, 若只想要快速上手, 只要下述三個步驟即可.

1. doxygen -g Doxygen # 產生 Doxygen 檔(預設設定檔)
2. vim Doxygen # 修改符合自己要得設定
3. doxygen Doxygen # 產生程式文件

Doxygen 相關文件

• Doxygen 首頁
• Doxygen - WikiPedia
• Doxygen 說明頁面
• Doxygen Config - 設定檔所有參數說明
• Doxygen Usage - 如何使用
• Doxygen 參數清單 - @param, @brief 等等, 有哪些變數可以使用, 參考此篇
• Doxygen Start - 快速入手
• Doxygen 快速入門 - 這篇快速入門是中文版(Big5)

Doxygen 操作、設定

產生一份 Doxygen 預設 Config 檔, 並由此設定檔來修改.

指令

• doxygen -g <config-file>
• doxygen -g # 會產生 Doxyfile
• doxygen -g Doxygen # 產生檔名叫 Doxygen 的預設 Config 擋
• doxygen -w html header.html footer.html stylesheet.css <config_file> # 產生文件到 html 目錄

操作

1. doxygen -g Doxygen # 產生 Doxygen 的設定檔, 都是預設值
2. vim Doxygen # 下述是我有做修改的部份, 請依照自己的需求設置
   

   PROJECT_NAME       = PROJECT_NAME
   PROJECT_NUMBER     = 1.0
   OUTPUT_DIRECTORY   = ../docs
   CREATE_SUBDIRS     = YES
   EXTRACT_ALL        = YES
   OUTPUT_LANGUAGE    = Chinese-Traditional # default: English
   FULL_PATH_NAMES    = NO # default: YES
   EXTRACT_STATIC     = YES # default: NO
   FILE_PATTERNS      = *.php
   RECURSIVE          = YES # default: NO
   REFERENCED_BY_RELATION = YES # default: NO
   REFERENCES_RELATION    = YES # default: NO
   INLINE_SOURCE = YES # 要不要把 source code 印在文件裡面

若要將所有 Function 都列出來, 需要設下面參數, 不然只會列出物件的程式文件.

• EXTRACT_ALL  = YES # 這會列出所有檔案

其他參考可見此篇, 下述取自: CSCI 102: Doxygen Tutorial

• EXTRACT_ALL = YES
  • Extract documentation even from those elements you haven't yet commented.
• INLINE_SOURCE = YES
  • Extract the relevant parts of the source and associate them with your description.
• HAVE_DOT = YES
  • Use Graphviz for class and collaboration diagrammes.
• CALL_GRAPH = YES
  • Generate a dependency graph for functions and methods.
• GENERATE_LATEX = NO
  • Skip generating LaTeX sources for PDF.

Doxygen 參數清單

Doxygen 於註解中, 有哪些特定的參數可以用 (ex: @param), 可參考此篇: Doxygen 參數清單 (此文中的 "\" 可以用 "@" 代替)

Doxygen 常用註解範例

• 多行註解
  

  /** Brief description which ends at this dot. Details follow
  * here.
  */
  或
  /**
  * Brief description which ends at this dot. Details follow
  * here.
  */

• 單行註解
  

  /** Brief description (e.g.\ using only a few words). Details follow. */

• List
  

  /**
  * Text before the list
  * - list item 1
  * - sub item 1
  * - sub sub item 1
  * - sub sub item 2
  * .
  * The dot above ends the sub sub item list.
  * More text for the first sub item
  * .
  * The dot above ends the first sub item.
  * More text for the first list item
  * - sub item 2
  * - sub item 3
  * - list item 2
  * .
  * More text in the same paragraph.
  *
  * More text in a new paragraph.
  */

• Group
  

  /** @defgroup group1 The First Group
  * This is the first group
  * @{
  */

  /** @brief class C1 in group 1 */
  class C1 {};

  /** @brief class C2 in group 1 */
  class C2 {};

  /** function in group 1 */
  void func() {}

  /** @} */ // end of group1

• Link
  

  <a href="linkURL">link text</a>

Doxygen 產生文件

上述設定全部完成後, 再來就是執行來產生文件, 執行下述即可.

1. doxygen Doxygen # Doxygen 是設定檔名稱, 此步驟會開始產生文件
2. 再來就可以在 "../docs" (依照設定檔 OUTPUT_DIRECTORY 的參數而定) 看文件囉~