Powerful code edging tools - DOXYGEN
Author: Sese http://blog.9cbs.net/sese this original article without permission of the author may not be reproduced
Doxygen is what doxygen stem comes from Document (document) and Oxygen (oxygen), which is a powerful, easy to use code document generation system that supports various operating systems and programming languages. Doxygen is developed by Dutch Dimitri Van Hesch. It is published under the GNU Public License (GPL), which has now become an attached component of the major Linux distribution. Many heavyweight software items (such as KDE, QT, ACE libraries, etc.) are selected to generate project documents as their edging tools.
Doxygen is initially developed under Linux, but has been ported to multiple operating system platforms, including the release of Unix, MS Windows, and Mac OS. Doxygen is currently the latest version is
1.3.6
Supported programming languages include C , C, Java, IDL (CORBA and MS style), which supports Objective-C, PHP, C #, and D language. Doxygen's function Doxygen's main function is to analyze and extract code annotations written in a specific tag format (supported note format with Java DOC 1.1, QT-DOC, And Kdoc format), generate project documents in multiple formats, currently supported documents The format is as follows: l Taking the HTML L POSTScript L Unlink PDF L XML L Unix Man Page L Compressed HTML (CHM) L RICH TEXT FORMAT (RTF) L MS Word
Workflow Doxygen consists of a configuration file parser, a variety of programming languages, and a builder of a variety of target format documents, and its working principle is shown in the following figure:
The above flowchart illustrates the basic working principle of Doxygen. Doxygen reads all configuration information required for work from the configuration file (also called DoxyFile). Doxygen's profile is a plain text file, you can edit software editing with any text, below is part of a configuration file (long standing space, so it is omitted):
# Doxyfile
1.3.3
Project_name = ace
Output_directory =.
Output_Language = ENGLISH
INPUT = DOCS /
ACE /
ACE / OS_INCLUDE /
ACE / OS_INCLUDE / ARPA /
ACE / OS_INCLUDE / NET /
ACE / OS_INCLUDE / NETINET /
ACE / OS_INCLUDE / SYS
File_patterns = * .h /
* .cpp /
* .inl /
* .i /
*.TXT
Source_Browser = YES
Inline_sources = YES
Strip_code_comments = no
Generate_html = YES
HTML_OUTPUT = HTML / ACEHTML_FILE_EXTENSION = .html
Doxygen's configuration file consists of several configuration items, each line is usually a configuration item, followed:
Item_name = Value
Written in the format, the comment line begins with "#", and when the configuration item is more than one line, it is "/". In the configuration file, specify the source code directory file as the input, generate document formats, languages, and other configuration options for user customization. The complete Doxygen configuration file item exceeds 200 items, and the user can take quite accurate control of the generated project document.
In order to facilitate the user to write a configuration file, Doxygen also provides a graphical configuration tool DoxyWizard, which can be used under the platform of the graphical user interface (X-Window, MS Windows, etc.), greatly simplifies the workload of the configuration file, the interface of DoxyWizard As follows:
After generating a configuration file (whether using DoxyWizard or manually written), you can start generating a project document with simply executing the following command:
$ doxygen
If you use the user using the DoxyWizard graphics, you only need to click the Run option in the toolbar or menu to generate a document. It should be noted that DOXYGEN can directly generate four document formats in the document format, and four other files, other file formats need to be further converted through third-party tools, but usually this conversion process is also very easy because doxygen will These third-party tools generate the desired configuration or project file, which gives the following table give more other document formats supported by Doxygen, and the conversion tool:
Indirect document format
based on
Third-party tool
project files
PostScript Latex Ghostscript Makefile Pdf Latex Ghostscript Makefile Chm HTML MS HTML WORKSHOP HHP MS WORD RTF MS WORD
It is worth mentioning that because Doxygen supports the XML format output, the user can write an additional handler to generate a fully customized project document. To automatic editing, the goal of the comment automatic edging technology is that the programmer writes the annotation of the writer, and can effectively become a standard document, minimize the number of documents, and improve software productivity. The principle of automatic edging is that the programmer uses a comment tag that complies with the programming language annotation syntax but also distinguishes (thus capable of dogen recognition), the Doxygen tool performs similar compilation when processing the code. The grammar analysis process, combines those code structures (class, methods, variables such as rules) (class, methods, variables, etc.) that meet the rules, and the grammar information, thereby forming an output document. Doxygen supports a variety of mainstream platforms or library annotations, and has their own extensions, in fact, several annotation formats are similar, as follows: Java-Doc format:
/ **
... Text ...
* /
QT-DOC format:
/ *!
... Text ...
* /
Doxygen extension:
(Single line)
/// text
(6th)
Some-statements; / *
Some-statements; //
In addition, in the Doxygen Comment Block, you can use Doxygen predefined instructions (Command) to generate some specific document tags, for example, the following comment block: / *! @ Param * a pointing to the plum 1
@Param * B Point points to plus 2
@Param * C Computing
@return error code
@SA Compminus
* /
INTCOMPMULTIPLY (const complex * b, complex * c)
Use @ param, @ return, and @sa to mark the parameters, return, and see the document block, the actually generated document is as follows:
INTCOMPMULTIPLY (const complex * b, complex * c)
Parameters: * a pointer to multiplier 1 * b pointing to the pointer of multiplier 2 * C Complete return: Error code See: Compminus
Doxygen defines a total of more than 100 different commands to control the generation format of the document, and Doxygen also supports the HTML code to directly insert comments to generate documents, support custom documents, footer, footer. Interested readers can refer to Doxygen's related documents to learn complete instructions. Advanced Graphics Characteristics Doxygen can draw a variety of graphics inserted documents via the support of Graphviz open source tools, including file include relationships, object inheritance relationships, etc. Next is several examples (all from famous open source C libraries ACE): file include relationship :
Class inheritance:
More powerful is that these graphics generated by Doxygen support interactive navigation (valid in the HTML format), and document users can switch to the corresponding page, which is very convenient, and all these only need to set the following Simple configuration options: dot_path = #graphviz path
Dot_image_format = # picture format, default is PNG
Class_Diagrams = # Whether to draw a graph
Collaboration_Graph = # Whether to draw a collaboration map
UML_LOOK = # Using UML style
INCLUDE_GRAPH = #include relationship
Call_graph = # Call diagram
Graphical_hierarchy = # inheritance diagram
Internationalization of Doxygen's authors have considered the needs of multi-language support when designing, providing built-in support. Currently, Doxygen can work correctly in nearly 30 languages, only need to point out the required language in the configuration file. Type, for example, if you want Doxygen to generate a Chinese version of the document, just set the Output_Language tag in the configuration file to Chinese. However, it is worth explanation. If you generate the Latex file generated by Doxygen, if you have a Chinese macro, you need to have a Chinese macro package, you can generate Chinese PS and PDF files. For more details, see Latex Chinese. data. learn more
The official homepage of Doxygen is: http://www.stack.nl/~dimitri/doxygen/, from here you can download to the latest Doxygen distribution, source code, and documentation.
