Doxygen configuration (translation)

Source: Internet
Author: User
Tags format definition command line config functions tagname variable root directory
Configuration to use when using the Doxygen Document development tool:

The executable file Doxygen is the primary tool for analyzing and generating documents in the original code. See the Doxygen Usage section for more detailed use assistance.

The Doxytag executable---is only intended to help programmers build reference documents for Doxygen documents that do not need to look at the original code to understand the engineering deployment information (for example, those that use Doxygen). See the Doxytag Usage section for more help with your usage.

Doxywizard executables are easy to use and are a graphical tool used to provide configuration information for the Doxygen tool.

The following figure shows the information about the interrelationships between development tools:


Figure: Doxygen Information flow

Step 1: Create a configuration file
Doxygen uses a configuration file to determine all of its settings. Each project should have its own configuration file.

A project can have only one original file, or it can be a recursive scan of all the original files in the project to get the original file tree view.

To simplify the work of Doxygen generating configuration files, Doxygen can provide you with a templated configuration file.

1. In order to create a templated configuration file, you only need to invoke Doxygen and then typed-G from the command line:

Doxygen-g <config-file>
where <config-file> is the filename of a templated configuration file. If you omit the filename, Doxygen will generate a default Doxyfile configuration file for you. If <config-file> is a file name that already exists, Doxygen will generate a <config-file&gt before the configuration template is generated. Bak back up files.

2. If you use-(for example, a minus sign) as the filename Doxygen will take the text you enter from the keyboard as the profile name.

The configuration file has a similar format to makefile. The main is: contains a lot of "logo" allocation format (tags):

For example:


When you generate a document template, you can use the default (that is, retain most tags) for more information, see the Configuration section.

If you do not want to use text editing tools to write configuration files, you should look at the description of the Doxywizard section, a graphical tool that can be used to create/read/write Doxygen configuration documents, and it can also be configured in a path full path to make Doxygen work properly.

3. For a C + + project with very few original files and header files, you can keep the INPUT flag "empty", then Doxygen will search for the original file under the current path.

4. If your project is large, you should put the "root directory" of your project files behind the input sign, the files that need to be added to the project should be placed after the FILE_PATTERNS flag (for example: *.cpp *.h). At a minimum, a file that matches 1 items can be read and parsed by the Doxygen program (if omitted, the format in the Doxygen configuration list is used).

5. If you want to parse the original file tree recursively, you must set the recursive flag to Yes.

6. To use more custom rules for analysis in Doxygen, you must use the EXCLUDE and Exclude_patterns flags.

7. To ignore all files under the test path, use the following form:

Exclude_patterns = */test/*
8. Typically, the Doxygen is directly analyzed for the C + + file. If the file has an. idl or. odl extension, Doxygen treats it as an IDL file.

8. A. java extension will be treated as a Java file.

9. Files that use. cs as extensions will be treated as C # files.

10. Files using the. php,. php4 extensions, and files with the. Inc OR. phtml extensions will be treated as PHP's original files.

11. If you want to use Doxygen to generate documentation for existing projects. The first thing you need to think about is what kind of formatting your engineering document will ultimately use, and in order to achieve such a goal, you have to set the Extract_all flag to Yes. Then, Doxygen shows that it knows all the configuration goals of your engineering files.

Note: If you set the Extract_all flag to Yes. Then: Warnings such as undocumented members will not be produced again.

12. The use of Doxygen to analyze a part or all of an existing source code can provide a clearer understanding of the definition of each functional module and the functions to be implemented and the cross-reference between them.

13. Generate cross Reference using Doxygen must set the SOURCE_BROWSER flag to YES. You can also include all of the project's source code in the document directly by setting the INLINE_SOURCES flag to YES. (This facilitates the browse of the code).

Step 2:running Doxygen
To generate the documentation can now enter:

Doxygen <config-file>
Doxygen will create HTML, RTF, Latex, and/or man paths in the output path. The file format in the path and path is the corresponding HTML, RTF, and Unix-man format.

The default path is the Doxygen installation path. You can use the Output_directory, Html_output, Rtf_output, Latex_output, and Man_output flags to customize the output path of the configuration document. If the output path does not exist Doxygen will create an output path for you.

The generated HTML can browse through the index.html files located under the HTML path by using the browser. If the browser supports cascading style sheets (CSS) that would be great.

The generated must be compiled first with the compiler (I use the teTeX 0.9 version, which contains 3.14159). To simplify the build process of compiling documents, Doxygen provides a makefile under the latex path. Typing make under the command line latex path will generate a Refman.dvi file. (Suppose you have a file called make of course). You can view the file by using the XDVI command or use Dvips to convert it to a suffix that is. ps file

You can use the make Ps_2on1 command to achieve an effect that is divided into 2 pages. The PostScript file will eventually be sent to the PostScript printer output. If you don't have a PostScript printer, you can use the Ghostscript command to convert the PostScript file format to a file format that your printer recognizes. If you have already installed the Ghostscript interpreter, you can convert the file to PDF format, which requires typing a make PDF (or made pdf_2on1).

To generate a PDF file, you set the PDF_HYPERLINKS flag to Yes.

The resulting man paging file can be viewed through the man program. However, you must determine that the man path has the appropriate environment variable settings (generally in the MANPATH environment variable). Note: The man page file format has some limitations, so some information (like: Class diagram, cross Reference, formula, etc.) will be lost.

Step 3:documenting The sources
Although source code documentation is taken as the 3rd step, this is done as step 1th in some new projects. Here, I assume you have some source code that you want to use Doxygen to document (describe API interfaces and functions).

If the Extract_all option is set to No (the default is no), then Doxygen will only generate documents for the members, files, classes, and namespaces that have been documented. What if your document is in this situation? For members, there are 2 basic settings for classes and namespaces:

1. The front of a member, class, or namespace arranges a description or definition of a block. For files, classes, and namespace members, Doxygen allows documents to be arranged directly behind members. You can refer to:

Special documentation Blocks Learn more about the settings for special blocks.

2. You want to deploy special document blocks (any file or any path) anywhere, and add a "structured" command to the document block. The "structured" command is used to set up a link that can be compiled into a document. (e.g. a, class, namespace or file). See: Documentation at the other places learn more about how to use structured commands.

The file can only be set using the method in the 2 above, because there is no way to put a document block in front of a file.

Of course, file members (functions, variables, type definitions, define) do not need to be displayed using the "structured" command, just put the special document block to the front or end of the file.

Document blocks inside a document perform Doxygen parsing before output in HTML format or other format output file:

It's actually an analysis before you do the following steps:

When special "structured" commands inside a document are executed. See the Special Commands section for all command reference information.
If a row uses "Space + followed by 1 or more *", or many "space" characters, all spaces and "*" will be deleted.
All "blank Lines" are considered "graphic separators." This arrangement allows you to have the ability to "deploy custom graphics separators" to produce more readable documents.
Doxygen will generate links for all classes that have been archived.
If you find a member in your document that conforms to the Doxygen document format, you also create a link for the members. Please refer to: Automatic link generation get more information on how to automate document linking.
The HTML flags in the document are interpreted and converted to the corresponding output. See: HTML Command

Contact Us

The content source of this page is from Internet, which doesn't represent Alibaba Cloud's opinion; products and services mentioned on that page don't have any relationship with Alibaba Cloud. If the content of the page makes you feel confusing, please write us an email, we will handle the problem within 5 days after receiving your email.

If you find any instances of plagiarism from the community, please send an email to: and provide relevant evidence. A staff member will contact you within 5 working days.

A Free Trial That Lets You Build Big!

Start building with 50+ products and up to 12 months usage for Elastic Compute Service

  • Sales Support

    1 on 1 presale consultation

  • After-Sales Support

    24/7 Technical Support 6 Free Tickets per Quarter Faster Response

  • Alibaba Cloud offers highly flexible support services tailored to meet your exact needs.