• <ins id="pjuwb"></ins>
    <blockquote id="pjuwb"><pre id="pjuwb"></pre></blockquote>
    <noscript id="pjuwb"></noscript>
          <sup id="pjuwb"><pre id="pjuwb"></pre></sup>
            <dd id="pjuwb"></dd>
            <abbr id="pjuwb"></abbr>

            tqsheng

            go.....
            隨筆 - 366, 文章 - 18, 評(píng)論 - 101, 引用 - 0
            數(shù)據(jù)加載中……

            Doxygen入門(1)--基礎(chǔ)知識(shí)


            來自:http://www.stack.nl/~dimitri/doxygen/starting.html

            Getting started

            The executable doxygen is the main program that parses the sources and generates the documentation. See section Doxygen usage for more detailed usage information.

            [可執(zhí)行的 doxygen 是一種源文件轉(zhuǎn)換及文檔生成工具,具體使用信息請(qǐng)參見 Doxygen用法 ]

            The executable doxytag is only needed if you want to generate references to external documentation (i.e. documentation that was generated by doxygen) for which you do not have the sources. See section Doxytag usage for more detailed usage information.

            [可執(zhí)行的 doxytag 是一種外部文檔索引生成工具,當(dāng)然所謂外部文檔也是應(yīng)由 doxygen 生成的,doxytag 特別適合于所基于的外部文檔不包含源程序時(shí)的情況。具體查看 Doxytag 用法 ]

            Optionally, the executable doxywizard can be used, which is a graphical front-end for editing the configuration file that is used by doxygen and for running doxygen in a graphical environment. For Mac OS X doxywizard will be started by clicking on the Doxygen application icon.

            [另外,可執(zhí)行的 doxywizard 是一種前端圖形工具,用于配置文件的編輯。如果在 Mac 中使用 doxywizard 可以直接點(diǎn)擊 Doxygen 應(yīng)用程序圖標(biāo)。]

            The following figure shows the relation between the tools and the flow of information between them (it looks complex but that's only because it tries to be complete):

            [下圖說明了工具和信息流向的關(guān)系,雖然看起來有些復(fù)雜,但其實(shí)很簡單,當(dāng)然復(fù)雜也是因?yàn)?Doxygen 期望能夠提供更完善的功能。]

            infoflow.gif

            Doxygen information flow

            Step 1: Creating a configuration file [第一步:創(chuàng)建配置文件]

            Doxygen uses a configuration file to determine all of its settings. Each project should get its own configuration file. A project can consist of a single source file, but can also be an entire source tree that is recursively scanned.

            [Doxygen 使用配置文件來決定使用中所有的設(shè)置。每個(gè)項(xiàng)目應(yīng)該擁有自己的配置文件。這里所說的項(xiàng)目可以包含一個(gè)文件的項(xiàng)目,當(dāng)然更適合的是包括整個(gè)源文件樹中所有文件的項(xiàng)目。]

            To simplify the creation of a configuration file, doxygen can create a template configuration file for you. To do this call doxygen from the command line with the -g option:

            [為了簡化配置文件的創(chuàng)建, doxygen 提供了配置模板,使用如下命令即可:]

            doxygen -g <config-file>

            where <config-file> is the name of the configuration file. If you omit the file name, a file named Doxyfile will be created. If a file with the name <config-file> already exists, doxygen will rename it to <config-file>.bak before generating the configuration template. If you use - (i.e. the minus sign) as the file name then doxygen will try to read the configuration file from standard input (stdin), which can be useful for scripting.

            [其中 <config-file> 是配置文件的名稱。如果忽略該項(xiàng),默認(rèn)的文件名將被創(chuàng)建,即 Doxyfile。如果指定的 <config-file> 已經(jīng)存在,doxygen 將重命名原來的文件為 <config-file>.bak,之后再生成新的配置模板。如果我們使用 -(減號(hào))作為文件名,doxygen 將嘗試從標(biāo)準(zhǔn)輸入(stdin)讀取配置信息,這種方式特別適合于自寫腳本。]

            The configuration file has a format that is similar to that of a (simple) Makefile. It consists of a number of assignments (tags) of the form:

            [配置文件的格式類似于簡單的 Makefile,它包含一些具有賦值格式的標(biāo)簽,如下:]

            TAGNAME = VALUE or 
            TAGNAME = VALUE1 VALUE2 ... 

            You can probably leave the values of most tags in a generated template configuration file to their default value. See section Configuration for more details about the configuration file.

            [我們可以保留大部分標(biāo)簽的默認(rèn)值,參見具體配置說明。]

            If you do not wish to edit the config file with a text editor, you should have a look at doxywizard, which is a GUI front-end that can create, read and write doxygen configuration files, and allows setting configuration options by entering them via dialogs.

            [如果我們不希望以文本形式編輯配置文件,我們可以使用 doxywizard,它是一個(gè) doxygen 的前端 gui,用以創(chuàng)建、讀取、編輯 doxygen 配置文件,可以通過對(duì)話框選擇配置選項(xiàng)。]

            For a small project consisting of a few C and/or C++ source and header files, you can leave INPUT tag empty and doxygen will search for sources in the current directory.

            [對(duì)于只包含幾個(gè)C或C++源文件及頭文件的小項(xiàng)目來說,我們可以使 INPUT 標(biāo)簽留空,這樣 doxygen 將在當(dāng)前文件夾中搜尋所有的源文件。]

            If you have a larger project consisting of a source directory or tree you should assign the root directory or directories to the INPUT tag, and add one or more file patterns to the FILE_PATTERNS tag (for instance *.cpp *.h). Only files that match one of the patterns will be parsed (if the patterns are omitted a list of source extensions is used). For recursive parsing of a source tree you must set the RECURSIVE tag to YES. To further fine-tune the list of files that is parsed the EXCLUDE and EXCLUDE_PATTERNS tags can be used. To omit all testdirectories from a source tree for instance, one could use:

            [如果處理包含一個(gè)源文件目錄的大項(xiàng)目,我們應(yīng)該令 INPUT 標(biāo)簽等于源文件根目錄和相應(yīng)的目錄,并添加文件類型
            標(biāo)簽 FILE_PATTERNS (如 *.cpp、*.h)。只有匹配文件類型的文件才會(huì)被處理,如果該標(biāo)簽忽略不指明,則“源文件
            擴(kuò)展列表”將被采用。如果希望迭代處理源代碼樹,你必須設(shè)置 RECURSIVE 為 YES。如果希望更精確地控制文件
            類型列表,還可以使用 EXCLUDEEXCLUDE_PATTERNS 。如下面列子,如果需要忽略掉 test 目錄下的所有文件,
            可以這樣處理:]

            EXCLUDE_PATTERNS = */test/*

            Doxygen looks at the file's extension to determine how to parse a file. If a file has an .idl or .odl extension it is treated as an IDL file. If it has a .java extension it is treated as a file written in Java. Files ending with .cs are treated as C# files and the .py extension selects the Python parser. Finally, files with the extensions .php.php4,.inc or .phtml are treated as PHP sources. Any other extension is parsed as if it is a C/C++ file, where files that end with .m are treated as Objective-C source files.

            [Doxygen 是通過文件的擴(kuò)展名來決定如何處理文件的。如果某個(gè)文件擴(kuò)展名為 .idl 或 .odl,那么這個(gè)文件即被認(rèn)為

            是 IDL 文件。如果某個(gè)具有 .java 擴(kuò)展名,那么即被認(rèn)為是由 Java 語言寫成的文件。同樣,.cs 是 C# 文件,.py 文件

            作為 Python 來處理;.php、.php4、.inc 或 .phtml 被認(rèn)為是 PHP 源文件。其他的就被認(rèn)為是 C/C++文件處理,其中

            以 .m 結(jié)尾的被認(rèn)為是 Object-C 文件處理。]

            If you start using doxygen for an existing project (thus without any documentation that doxygen is aware of), you can still get an idea of what the structure is and how the documented result would look like. To do so, you must set the EXTRACT_ALL tag in the configuration file to YES. Then, doxygen will pretend everything in your sources is documented. Please note that as a consequence warnings about undocumented members will not be generated as long as EXTRACT_ALL is set to YES.

            [如果你使用 doxygen 對(duì)現(xiàn)有項(xiàng)目進(jìn)行處理(也就是說目前 doxygen 對(duì)要處理的項(xiàng)目還一無所知),我們可以先規(guī)劃出未來成品的結(jié)構(gòu)如何,或者是明確到底以什么樣子呈現(xiàn)。為實(shí)現(xiàn)該目的,我們必須設(shè)置 EXTRACT_ALL 標(biāo)簽為 YES。這樣,doxygen 將記錄源文件中所有內(nèi)容。請(qǐng)注意:使用了該標(biāo)簽后,未記錄的成員或文件內(nèi)容將不會(huì)得到任何提示或警告。]

            To analyse an existing piece of software it is useful to cross-reference a (documented) entity with its definition in the source files. Doxygen will generate such cross-references if you set the SOURCE_BROWSER tag to YES. It can also include the sources directly into the documentation by setting INLINE_SOURCES to YES (this can be handy for code reviews for instance).

            [另外,使用交叉引用(鏈接源文件定義片斷)在軟件分析中十分有效,Doxygen 將在 SOURCE_BROWSER 為 YES 的情況下自動(dòng)產(chǎn)生交叉引用。如果設(shè)置 INLINE_SOURCES 為 YES,可以使源代碼直接加入到文檔中,這對(duì)代碼復(fù)審非常有用。]

            (自己注:記得將 OUTPUT_LANGUAGE=Chinese)

            Step 2: Running doxygen [第二步:運(yùn)行 doxygen]

            To generate the documentation you can now enter: [我們可以直接使用以下命令產(chǎn)生文檔:]
            doxygen <config-file>

            Depending on your settings doxygen will create htmlrtflatexxml and/or man directories inside the output directory. As the names suggest these directories contain the generated documentation in HTML, RTF, $\mbox{\LaTeX}$, XML and Unix-Man page format.

            [通過不同的設(shè)置,doxygen 可以在輸出目錄中生成各種文件夾,如何 html、rtf、latex、xml 或 man等,并分別代表所生成的 HTML、RTF、XML以及 $\mbox{\LaTeX}$, Unix-Man 格式文檔。]

            The default output directory is the directory in which doxygen is started. The root directory to which the output is written can be changed using the OUTPUT_DIRECTORY. The format specific directory within the output directory can be selected using the HTML_OUTPUTRTF_OUTPUTLATEX_OUTPUTXML_OUTPUT, and MAN_OUTPUT tags of the configuration file. If the output directory does not exist, doxygen will try to create it for you (but it will nottry to create a whole path recursively, like mkdir -p does).

            [默認(rèn)的輸出文件夾為當(dāng)前運(yùn)行 doxygen 的文件夾,當(dāng)然可以使用 OUTPUT_DIRECTORY 修改根目錄。另外,根目錄下特定的文件夾可以通過以下標(biāo)簽設(shè)置,即HTML_OUTPUTRTF_OUTPUTLATEX_OUTPUTXML_OUTPUT, 和 MAN_OUTPUT 。如果輸出文件夾不存在,那么 doxygen 將嘗試創(chuàng)建一個(gè)新的,但是不會(huì)象 mkdir -p 一樣工作。]

            HTML output

            The generated HTML documentation can be viewed by pointing a HTML browser to the index.html file in the htmldirectory. For the best results a browser that supports cascading style sheets (CSS) should be used (I'm using Mozilla, Safari, Konqueror, and sometimes IE6 to test the generated output).

            [生成的 HTML 文檔通過 index.html 起始,這些 HTML 文檔采用 CSS。]

            Some of the features the HTML section (such as GENERATE_TREEVIEW) require a browser that supports DHTML and Javascript.

            [還有一些特性(如 GENERATE_TREEVIEW)需要瀏覽器支持 DHTML 和 Javascript。]

            If you plan to use the search engine (see SEARCHENGINE), you should view the HTML output via a PHP-enabled web server (e.g. apache with the PHP module installed).

            [如果你計(jì)劃使用搜索引擎(見SEARCHENGINE)你應(yīng)當(dāng)通過 php web服務(wù)器來查看 html 輸出。]

            LaTeX output

            The generated $\mbox{\LaTeX}$ documentation must first be compiled by a $\mbox{\LaTeX}$ compiler (I use a recent teTeX distribution). To simplify the process of compiling the generated documentation, doxygen writes a Makefile into the latexdirectory.

            The contents and targets in the Makefile depend on the setting of USE_PDFLATEX. If it is disabled (set to NO), then typing make in the latex directory a dvi file called refman.dvi will be generated. This file can then be viewed using xdvi or converted into a PostScript file refman.ps by typing make ps (this requires dvips).

            To put 2 pages on one physical page use make ps_2on1 instead. The resulting PostScript file can be send to a PostScript printer. If you do not have a PostScript printer, you can try to use ghostscript to convert PostScript into something your printer understands.

            Conversion to PDF is also possible if you have installed the ghostscript interpreter; just type make pdf (or make pdf_2on1).

            To get the best results for PDF output you should set the PDF_HYPERLINKS and USE_PDFLATEX tags to YES. In this case the Makefile will only contain a target to build refman.pdf directly.

            RTF output

            Doxygen combines the RTF output to a single file called refman.rtf. This file is optimized for importing into the Microsoft Word. Certain information is encoded using field. To show the actual value you need to select all (Edit - select all) and then toggle fields (right click and select the option from the drop down menu).

            XML output

            The XML output consists of a structured "dump" of the information gathered by doxygen. Each compound (class/namespace/file/...) has its own XML file and there is also an index file called index.xml.

            A file called combine.xslt XSLT script is also generated and can be used to combine all XML files into a single file.

            Doxygen also generates two XML schema files index.xsd (for the index file) and compound.xsd (for the compound files). This schema file describes the possible elements, their attributes and how they are structured, i.e. it the describes the grammar of the XML files and can be used for validation or to steer XSLT scripts.

            In the addon/doxmlparser directory you can find a parser library for reading the XML output produced by doxygen in an incremental way (see addon/doxmlparser/include/doxmlintf.h for the interface of the library)

            Man page output

            The generated man pages can be viewed using the man program. You do need to make sure the man directory is in the man path (see the MANPATH environment variable). Note that there are some limitations to the capabilities of the man page format, so some information (like class diagrams, cross references and formulas) will be lost.

            Step 3: Documenting the sources[第三步:標(biāo)記源文件]

            Although documenting the sources is presented as step 3, in a new project this should of course be step 1. Here I assume you already have some code and you want doxygen to generate a nice document describing the API and maybe the internals as well.

            [雖然標(biāo)記源文件放在了第三步,但實(shí)際上對(duì)于一個(gè)新項(xiàng)目來說,這應(yīng)該是第一步。這里我們假設(shè)你已經(jīng)有一些代碼,并想利用 doxygen 來生成漂亮的文檔以描述 API 或內(nèi)部細(xì)節(jié)等。]

            If the EXTRACT_ALL option is set to NO in the configuration file (the default), then doxygen will only generate documentation for documented members, files, classes and namespaces. So how do you document these? For members, classes and namespaces there are basically two options:

            [如果 EXTRACT_ALL 標(biāo)簽設(shè)置為 NO(默認(rèn)值),那么 doxygen 只生成已經(jīng)標(biāo)記的成員、文件、類及命名空間。所以我們?cè)撊绾螛?biāo)記它們,這里對(duì)成員、類、命名空間給出兩條基本原則:]

            1. Place a special documentation block in front of the declaration or definition of the member, class or namespace. For file, class and namespace members it is also allowed to place the documention directly after the member. See section Special documentation blocks to learn more about special documentation blocks.
            2. Place a special documentation block somewhere else (another file or another location) and put a structural command in the documentation block. A structural command links a documentation block to a certain entity that can be documented (e.g. a member, class, namespace or file). See section Documentation at other places to learn more about structural commands.
                  1、在成員、類、命名空間前放置特別的標(biāo)記塊。對(duì)于一個(gè)文件、類、命名空間等,同樣可以直接在成員后面加上標(biāo)記。詳見Special documentation blocks
            2、在另一個(gè)文件或位置放置特別的標(biāo)記塊,并在標(biāo)記塊中置入結(jié)構(gòu)化命令。結(jié)構(gòu)化命令將提供到某個(gè)記錄塊或某個(gè)位置的鏈接(如鏈接到成員、類、命名空間等。)詳見:Documentation at other places 

            Files can only be documented using the second option, since there is no way to put a documentation block before a file. Of course, file members (functions, variable, typedefs, defines) do not need an explicit structural command; just putting a special documentation block in front or behind them will do.

            [文件只能以上面第二種方式標(biāo)記,因?yàn)槲覀兪菦]有方式在一個(gè)文件前面置入標(biāo)記塊的。當(dāng)然,文件成員(包括函數(shù)、變量、類型定義、定義等)不需要明確的結(jié)構(gòu)化命令。只要在它們前面或后面放入特別的標(biāo)記塊即可。]

            The text inside a special documentation block is parsed before it is written to the HTML and/or $\mbox{\LaTeX}$ output files.

            [特別標(biāo)記塊中的文本將在輸出前被轉(zhuǎn)換。]

            During parsing the following steps take place: [轉(zhuǎn)換步驟:]

            • The special commands inside the documentation are executed. See section Special Commands for an overview of all commands.
            • [標(biāo)記中的特別命令被執(zhí)行,詳見: Special Commands ]
            • If a line starts with some whitespace followed by one or more asterisks (*) and then optionally more whitespace, then all whitespace and asterisks are removed.
            • [如果某行以 whitespace 加上一個(gè)或多個(gè)星號(hào)開始,后面可能還會(huì)有更多 whitespace,那么所有的 whitespace 和星號(hào)將被刪除]
            • All resulting blank lines are treated as a paragraph separators. This saves you from placing new-paragraph commands yourself in order to make the generated documentation readable.
            • [所有空行將被認(rèn)為是段落分隔。這會(huì)省去加入段落命令的麻煩。]
            • Links are created for words corresponding to documented classes (unless the word is preceded by a %; then the word will not be linked and the % sign is removed).
            • [創(chuàng)建標(biāo)記類的鏈接。如果鏈接文字前標(biāo)有 %,那么該文字將不會(huì)被認(rèn)為是鏈接,同時(shí)刪除 %]
            • Links to members are created when certain patterns are found in the text. See section Automatic link generationfor more information on how the automatic link generation works.
            • [創(chuàng)建標(biāo)記成員的鏈接。詳見:Automatic link generation ]
            • HTML tags that are in the documentation are interpreted and converted to $\mbox{\LaTeX}$ equivalents for the $\mbox{\LaTeX}$ output. See section HTML Commands for an overview of all supported HTML tags.
            • [文檔中的HTML標(biāo)簽被轉(zhuǎn)換。]

            Go to the next section or return to the index.

            posted on 2012-07-10 16:33 tqsheng 閱讀(554) 評(píng)論(0)  編輯 收藏 引用


            只有注冊(cè)用戶登錄后才能發(fā)表評(píng)論。
            網(wǎng)站導(dǎo)航: 博客園   IT新聞   BlogJava   博問   Chat2DB   管理


            久久久久国产亚洲AV麻豆| 久久人人超碰精品CAOPOREN| 手机看片久久高清国产日韩| 18岁日韩内射颜射午夜久久成人| 亚洲精品白浆高清久久久久久 | 国产亚洲美女精品久久久久狼| 久久国产色av免费看| 久久福利资源国产精品999| 欧美日韩精品久久久久| 久久一区二区三区免费| 久久久久亚洲AV无码专区网站| 精品无码人妻久久久久久| 久久亚洲综合色一区二区三区| 久久国产精品-久久精品| 国产精品久久久久久一区二区三区 | 色88久久久久高潮综合影院 | 国产综合久久久久| 精品久久久久久久久午夜福利| 久久久av波多野一区二区| 久久棈精品久久久久久噜噜| 7777久久亚洲中文字幕| 国产精品成人久久久久三级午夜电影 | 久久久久亚洲av成人网人人软件| 精品国产99久久久久久麻豆| 久久久噜噜噜久久熟女AA片 | 国产精品成人99久久久久 | 亚洲乱码日产精品a级毛片久久| 中文字幕无码久久人妻| 国色天香久久久久久久小说 | 久久青青色综合| 亚洲综合日韩久久成人AV| 72种姿势欧美久久久久大黄蕉| 国产精品伊人久久伊人电影| 波多野结衣久久| 久久99精品久久久久久hb无码| 国产2021久久精品| 少妇熟女久久综合网色欲| 国产美女久久精品香蕉69| 欧美精品丝袜久久久中文字幕| 久久久精品国产sm调教网站| 久久久精品日本一区二区三区|