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

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

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

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

Doxygen 相關文件

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 的參數而定) 看文件囉~

作者: Tsung

對新奇的事物都很有興趣, 喜歡簡單的東西, 過簡單的生活.

在〈Doxygen 程式文件產生器 與 簡易筆記〉中有 3 則留言

發表迴響

這個網站採用 Akismet 服務減少垃圾留言。進一步了解 Akismet 如何處理網站訪客的留言資料