來源:http://dev.csdn.net/article/63/63284.shtm
注意:可以任意轉載,但請註名出處
使用Doxygen文檔開發工具時需要進行的配置:
可執行文件 doxygen 是原代碼分析和生成文檔的主要工具. 請看 Doxygen usage 章節來獲取更詳細的使用幫助.
Doxytag可執行文件---僅僅是用來實現幫助程序員生成不需要看原代碼就能瞭解工程部署信息的doxygen文檔的參考文檔( 例如:那些使用doxygen生成的文檔).請看Doxytag usage 章節來獲得更多的使用幫助.
doxywizard 可執行文件很容易就能使用,它是用來爲doxygen工具提供配置信息的一個圖形化工具.
下面的圖顯示了開發工具之間的相互關係信息:
http://www.stack.nl/~dimitri/doxygen/infoflow.gif
圖:Doxygen information flow
Step 1: 創建一個配置文件
Doxygen使用一個配置文件來確定它所有的設置. 每個工程都應該有它自己的配置文件.
一個工程可以只有一個原文件, 也可以是工程中所有原文件的遞歸掃描得到的原文件的樹狀視圖。
爲了簡化doxygen生成配置文件的工作, doxygen 可以爲你提供一個模板化的配置文件.
1. 爲了創建一個模板化的配置文件,只需要調用doxygen並從命令行中敲入-g:
doxygen -g <config-file>其中 <config-file>是某個模板化的配置文件的文件名. 如果你省略了文件名, doxygen會爲你生成一個默認的Doxyfile的配置文件. 如果<config-file>是一個已經存在的文件名, doxygen 在生成配置模板之前,將會生成一個 <config-file>. Bak備份文件。
2. 如果你使用 - (例如:減號) 作爲文件名doxygen將會把你從鍵盤輸入的文字當作配置文件名。
配置文件有着和Makefile相似的格式.主要是:包含了很多的“標誌”分配符格式 (tags):
例如:
TAGNAME = VALUE or
TAGNAME = VALUE1 VALUE2 ...
在生成文檔模板時,你可以使用默認(即:保留大多數的TAGS)詳細信息請看 Configuration 這一章節來獲取更多的信息.
如果你不想使用文本編輯工具來編寫配置文件,你應該看看 doxywizard 章節的描述, 它是一個可以用來創建/讀/寫doxygen 配置文檔的圖形化工具,同時它也可以在路徑中進行全路徑配置來使doxygen正常工作。
3. 對於一個有很少的原文件和頭文件組成的C/C++工程來說, 你可以保留 INPUT 標誌爲“空” ,那麼 doxygen 將會在當前路徑下搜索原文件.
4. 如果你的工程很大,你應該把你的工程文件的“根目錄”放在INPUT標誌後面,需要添加到工程中的文件應該放到FILE_PATTERNS 標誌之後(例如: *.cpp *.h). 至少是匹配了1項的文件才能被doxygen程序讀入並分析(如果省略了這項設置,則會使用doxygen配置列表中的格式).
5. 如果想要遞歸對原文件樹進行分析必須設置RECURSIVE標誌爲 YES.
6. 想在doxygen中使用更多的自定義規則進行分析,必須使用EXCLUDE標誌和 EXCLUDE_PATTERNS標誌。
7. 想忽略所有的 test路徑下的文件,使用下面的形式:
EXCLUDE_PATTERNS = */test/* 8. 對於C/C++文件Doxygen通常直接進行分析。 如果文件有 .idl或 .odl 擴展名,則doxygen會把它視爲 IDL文件。
8. 有.java 擴展名的將被視爲Java文件.
9. 使用 .cs作爲擴展名的文件將會視爲C# 文件.
10. 使用.php, .php4擴展名的文件和用.inc 或 .phtml 擴展名的文件將被視爲PHP 原文件.
11. 如果你想用doxygen爲已經存在的工程生成文檔。你首先要想象一下你的工程文檔最終使用什麼樣的格式排版,爲了實現這樣的目標,你必須要設置EXTRACT_ALL 標誌爲YES. 然後,doxygen表現出來的是它知道了所有你的工程文件的配置目標。
注意:如果設置EXTRACT_ALL 標誌爲YES 。則:undocumented members 之類的警告將不會再產生。
12. 使用doxygen來分析一個現存的源代碼的某個部分或全部文件可以更清晰的明白源代碼各個功能模塊的定義和要實現的功能以及它們之間的交叉參考。
13. 使用Doxygen 生成交叉參考必須設置SOURCE_BROWSER 標誌爲 YES。也可以直接通過設置INLINE_SOURCES 標誌爲 YES 來實現把工程的所有源代碼包含進文檔中。(這樣方便了代碼的通覽).
Step 2: Running doxygen
To generate the documentation you can now enter:
doxygen <config-file>Doxygen 將會在輸出路徑中創建html, rtf, latex和/或man 路徑。 路徑和路徑中的文件格式是對應的HTML, RTF, 和Unix-Man格式.
默認的路徑是doxygen的安裝路徑。可以使用 OUTPUT_DIRECTORY, HTML_OUTPUT, RTF_OUTPUT, LATEX_OUTPUT, 和MAN_OUTPUT標誌來自定義配置文檔的輸出路徑。如果輸出路徑不存在doxygen將會爲你創建一個輸出路徑。
生成的 HTML 可以通過使用瀏覽器瀏覽位於html路徑下的 index.html 文件. 如果瀏覽器支持層疊樣式表 (CSS) 那就更棒了。
生成的 必須要先用 編譯器進行編譯(我使用 teTeX 0.9版本,其中包含了 3.14159). 爲了簡化編譯文檔的生成過程,doxygen在latex 路徑下提供了一個Makefile 。在命令行latex路徑下敲入 make將會生成一個refman.dvi文件。 (假設你有一個文件叫做make of course). 你可以通過使用xdvi命令來查看這個文件或者使用dvips把它轉換成一個後綴是.ps的文件 refman.ps。
想實現分成2頁的效果可以使用make ps_2on1命令。PostScript文件最終會被髮送到PostScript打印機輸出。如果你沒有PostScript打印機,你可以使用ghostscript 命令把PostScript文件格式轉換成你的打印機能夠識別的文件格式。如果你已經安裝了ghostscript 解釋程序,那麼可以把文件轉換成 PDF格式,這只需要敲入make pdf (或make pdf_2on1)。
想生成PDF文件,你要把 PDF_HYPERLINKS 標誌設置成YES。
產生的man頁面文件可以通過man程序來進行查看。但是,你必須確定man路徑有相應的環境變量設置 (一般在 MANPATH環境變量中)。注意:man頁面文件的格式有一些限制 ,所以有些信息(像:class圖,交叉參考,公式等)將會丟失掉。
Step 3: Documenting the sources
儘管源代碼編制文檔的被作爲第3步,但是,在某些新的工程中,這個是作爲第1步來做的。 這裏,我假設你已經有了一些想用doxygen來對其進行文檔化(描述API接口和作用)的源代碼。
如EXTRACT_ALL 選項被設置成NO(默認情況下是NO )那麼doxygen只會爲已經文檔化的成員,文件,類和命名空間生成文檔。如果你的文檔屬於這種情況,該怎麼辦呢?對於成員,類和命名空間有2種基本的設置:
1.成員,類或命名空間的前面安排一個描述或定義的塊兒。對於文件,類和命名空間成員來說,doxygen 允許直接在成員後面安排文檔。你可以參考:
Special documentation blocks 瞭解更多特殊塊兒的設置。
2. 想在任何地方部署特殊的文檔塊兒(任何的文件或任何的路徑)和在文檔塊中添加一個“結構化”的命令。“結構化”的命令用來設置一個可被編製成文檔的鏈接。 (e.g. a member, class, namespace or file)。請看:Documentation at other places 瞭解更多的結構化命令的使用方法。
文件只能使用上面2中的方法進行設置,因爲沒有辦法把一個文檔塊兒放到一個文件的前面。
當然,文件成員(函數,變量,類型定義,define)不需要顯示的使用“結構化”命令,只需要把特殊的文檔塊兒放到文件中的最前面或最後面就可以了。
文檔內部的文檔塊兒在輸出爲HTML格式或其他格式輸出文件之前進行doxygen的語法分析:
它其實是在進行下面的步驟前進行分析:
文檔內部的特殊“結構化”命令被執行的時候。請看: Special Commands 章節獲取所有的命令參考信息。
如果某行中使用“空格+後面使用1個或多個*號”,或者是很多的“空格”符,則所有的空格和“*”號都會被刪除。
所有的“空行”都會被視爲“圖形分隔符”。這項安排可以使你有“部署自定義圖形分隔符”的能力,以產生更具可讀性的文檔。
Doxygen將會爲所有已經歸檔的classes生成鏈接。
如果在文檔中找到符合doxygen文檔格式的成員,那麼也會爲members創建鏈接。請參考:Automatic link generation獲取更多的如何自動化文檔鏈接。
文檔中的HTML標誌被解釋和轉換成相應的輸出。請看:HTML Commands章節獲取更多的關於HTML標誌的使用信息。
來源:
http://shanzy.bokee.com/793962.html
翻譯)Doxygen 配置詳解(5)-----詞彙表- -
下面是需要涉及到的配置參數,通過對它們進行具體的設置能夠實現想要的自定義效果.......
有些地方翻譯的不太合適,請參照相關的鏈接來了解它所表示的意思........
通過用文本編輯工具打開通過Doxygen生成的配置文件,然後用Ctrl+F來查找相關的"設置詞彙",來進行自定義,得到想要的文檔顯示格式
配置選項可以被分成幾類。下面給出的命令開關(或者說:配置選項)以字母順序給出:
配置選項可以被分成幾類。下面給出的命令開關(或者說:配置選項)以字母順序給出:
ABBREVIATE_BRIEF //簡短摘要
ALIASES //別名
ALLEXTERNALS //所有外部文檔
ALPHABETICAL_INDEX //字母順序索引
ALWAYS_DETAILED_SEC //詳細描述部分
BINARY_TOC //二進制操作
BRIEF_MEMBER_DESC //簡短的成員描述
CALL_GRAPH //調用到的圖
CASE_SENSE_NAMES //檢測的範例的名字
CHM_FILE //CHM格式文件
CLASS_DIAGRAMS //類-表
CLASS_GRAPH //類-圖
COLLABORATION_GRAPH //相互調用關係圖
COLS_IN_ALPHA_INDEX //以列形式顯示的字母順序的索引
COMPACT_LATEX //壓縮的LATEX文檔
COMPACT_RTF //壓縮的RTF文檔
CREATE_SUBDIRS //創建一個"子目錄"
DETAILS_AT_TOP //文檔的詳細頭部
DIRECTORY_GRAPH //目錄圖
DISABLE_INDEX //禁用INDEX
DISTRIBUTE_GROUP_DOC //禁用文檔成組顯示
DOT_IMAGE_FORMAT //點陣圖形
DOT_MULTI_TARGETS //多個DOT目標
DOT_PATH //DOT路徑設置
DOT_TRANSPARENT //DOT轉換設置
DOTFILE_DIRS //DOTFILE 列表顯示
ENABLE_PREPROCESSING //允許"預處理"指令
ENUM_VALUES_PER_LINE //每行的枚舉值
ENABLED_SECTIONS //允許分段顯示
EXAMPLE_PATH //例子路徑
EXAMPLE_PATTERNS //例子用的文件格式(*.cpp, *.h , *.java等)
EXAMPLE_RECURSIVE //例子遞歸
EXCLUDE //可執行文件
EXCLUDE_PATTERNS //可執行文件格式(*.exe, *.dll等)
EXCLUDE_SYMLINKS //可執行的SYMLINKS
EXPAND_AS_DEFINED //規定的擴展
EXPAND_ONLY_PREDEF //預定義擴展
EXTERNAL_GROUPS //使用到的外部的文件
EXTRA_PACKAGES //使用到的外部插件包
EXTRACT_ALL //提取所有
EXTRACT_LOCAL_CLASSES //提取所有本地類
EXTRACT_LOCAL_METHODS //提取所有本地方法
EXTRACT_PRIVATE //提取所有private
EXTRACT_STATIC //提取所有static
FILE_PATTERNS //文件路徑
FILE_VERSION_FILTER //文件版本控制
FILTER_PATTERNS //控制格式(主版本:第1次版本:第2次版本號)
FILTER_SOURCE_FILES //原文件的版本控制
FULL_PATH_NAMES //全路徑名
GENERATE_AUTOGEN_DEF //生成自動定義文件形式
GENERATE_BUGLIST //生成BUG列表
GENERATE_CHI //生成"希臘字母"
GENERATE_DEPRECIATEDLIST //生成"評估"列表
GENERATE_HTML //生成HTML
GENERATE_HTMLHELP //生成HTMLHELP
GENERATE_LATEX //生成LATEX
GENERATE_LEGEND //生成圖例
GENERATE_MAN //生成MAN文件
GENERATE_PERLMOD //生成Perl腳本
GENERATE_RTF //生成RTF
GENERATE_TAGFILE //生成標誌文件
GENERATE_TESTLIST //生成TESTLIST
GENERATE_TODOLIST //生成TODOLIST
GENERATE_TREEVIEW //生成樹狀視圖顯示
GENERATE_XML //生成XML
GRAPHICAL_HIERARCHY //繼承圖表
GROUP_GRAPHS //組-圖
HAVE_DOT //隱藏DOT
HHC_LOCATION //隱藏位置
HIDE_FRIEND_COMPOUNDS //隱藏"複合的"友員類型
HIDE_IN_BODY_DOCS //隱藏文檔的主體
HIDE_SCOPE_NAMES //隱藏"作用域"名
HIDE_UNDOC_CLASSES //隱藏"未歸檔"的所有CLASS
HIDE_UNDOC_MEMBERS //隱藏"未歸檔"的所有的成員
HIDE_UNDOC_RELATIONS //隱藏"未歸檔"的關係
HTML_ALIGN_MEMBERS //HTML文檔中成員對齊方式
HTML_FOOTER //HTML腳註設置
HTML_HEADER //HTML頭部設置
HTML_OUTPUT //HTML輸出設置
HTML_STYLESHEET //HTML樣式設置
IGNORE_PREFIX //忽略哪些前綴
IMAGE_PATH //圖片的路徑設置
INCLUDE_GRAPH //包含-圖
INCLUDE_PATH //頭文件包含的路徑
INHERIT_DOCS //文檔的繼承關係
INLINE_INFO //內聯信息
INLINE_INHERITED_MEMB //通過"繼承"得到的內聯成員
INLINE_SOURCES //內聯部分的源代碼
INPUT //輸入設置
INPUT_FILTER //能夠接受的輸入文件的擴展名格式設置(重要)
INTERNAL_DOCS //內部文檔
JAVADOC_AUTOBRIEF //JAVADOC工具生成的文檔的"自動摘要"
LATEX_BATCHMODE //LATEX匹配方式
LATEX_CMD_NAME //LATEX 命令名
LATEX_HEADER //LATEX 頭部
LATEX_HIDE_INDICES //LATEX內部隱藏的包含
LATEX_OUTPUT //LATEX輸出
MACRO_EXPANSION //宏展開設置(重要)
MAKEINDEX_CMD_NAME //MAKEINDEX命令索引
MAN_EXTENSION //MAN擴展
MAN_LINKS //MAN 鏈接設置
MAN_OUTPUT //MAN輸出設置
MAX_DOT_GRAPH_DEPTH //DOT圖的最大深度
MAX_DOT_GRAPH_HEIGHT //DOT圖的最大高度
MAX_DOT_GRAPH_WIDTH //DOT圖的最大寬度
MAX_INITIALIZER_LINES //最大初始化行
MULTILINE_CPP_IS_BRIEF //多 個CPP文件的簡短描述
OPTIMIZE_OUTPUT_FOR_C //對C採用的優化設置
OPTIMIZE_OUTPUT_JAVA //對JAVA採用的優化設置
OUTPUT_DIRECTORY //輸出路徑設置(重要)
OUTPUT_LANGUAGE //輸出語言設置(重要)
PAPER_TYPE //紙張類型
PDF_HYPERLINKS //PDF格式超鏈接設置(重要)
PERL_PATH //perl路徑設置
PERLMOD_LATEX //perlmod LATEX
PERLMOD_PRETTY // perlmod PRETTY(漂亮/相當)
PERLMOD_MAKEVAR_PREFIX //perlmod MAKE文件版本 PREFIX
PREDEFINED //預先定義(重要)
PROJECT_NAME //工程名(重要)
PROJECT_NUMBER //工程的組成成員(重要)
QUIET //靜態量設置(重要)
RECURSIVE //遞歸和循環
REFERENCED_BY_RELATION //交叉參考(重要)
REFERENCES_RELATION //交叉參考的關係
REPEAT_BRIEF //重新設置"簡短說明"爲打開狀態
RTF_EXTENSIONS_FILE //RTF展開文件
RTF_HYPERLINKS //RTF超鏈接
RTF_OUTPUT //RTF輸出設置
RTF_STYLESHEET_FILE //RTF樣式文件
SEARCH_INCLUDES //搜索時需要包含什麼(重要)
SEARCHENGINE //搜索引擎設定(重要)
SHORT_NAMES //使短文件名生效
SHOW_DIRECTORIES //顯示目錄
SHOW_INCLUDE_FILES //顯示包含文件(一般NO,否則太大)
SHOW_USED_FILES //顯示被用到的文件(一般YES)
SKIP_FUNCTION_MACROS //跳過函數中的宏(重要),菜鳥最好別跳
SORT_BRIEF_DOCS //文檔的簡短摘要
SORT_MEMBER_DOCS //成員的簡短描述
SOURCE_BROWSER //原文件瀏覽路徑
STRIP_CODE_COMMENTS //排除哪些條碼形式註釋(重要)
STRIP_FROM_INC_PATH //排除哪些頭文件包含的註釋(重要)
STRIP_FROM_PATH //排除哪些條碼路徑設置
SUBGROUPING //子組設置(重要)
TAB_SIZE //TAB符SIZE設置(重要)
TAGFILES //標誌文件
TEMPLATE_RELATIONS //模板關係設置(重要)
TOC_EXPAND //TOC擴展
TREEVIEW_WIDTH //樹狀圖顯示的寬度設置(重要)
UML_LOOK //UML外觀設置(重要)
USE_WINDOWS_ENCODING //使用windows系統的編碼形式(重要)
VERBATIM_HEADERS //VERBATIM頭部(頭文件)
WARN_FORMAT //警告格式指定(重要)
WARN_IF_DOC_ERROR //如果文檔出錯則顯示警告
WARN_IF_UNDOCUMENTED //如果是未歸檔文件則顯示警告
WARN_LOGFILE //警告日誌文件設置
WARN_NO_PARAMDOC //無參數文檔警告形式設定
WARNINGS //警告設置(重要)
XML_DTD //XML文件類型定義(重要)
XML_OUTPUT //XML輸出設置(重要)
XML_PROGRAMLISTING //XML程序列表(重要)
XML_SCHEMA //XML模式設置(重要)
本文來自CSDN博客,轉載請標明出處:http://blog.csdn.net/yaosan/archive/2009/02/06/3866943.aspx