Doxygen use, configuration and examples

Doxygen is an open-source, cross-platform, document system that is described in a similar Javadoc style, and can be started from a set of archive source files to generate documents

Download Doxygen + Graphviz

Doxygen can generate dynamic documents

Graphviz can generate a view connection the function used in the. c file, the header file is generated a tree structure and can be generated after the corresponding function of the jump, convenient query function.

First, Doxygen the use of step 1.1Doxygen configuration method

1.1.1>doxygen's homepage

First modify project name, select the directory where you scanned the source code directory: Check scan recursively:

1.2> in the wizard topics mode, select all entities, you can output a relatively complete function, whether to include the source code to see their own situation, choose your own language below. This has to be C, so choose C or PHP.

1.3> in output, if you need to export the CHM format, tick the CHM, no HTML is required.

1.4> choose to use the Graphviz package in diagrams to output the Uml,graphviz package to help establish some tree views.

1.5>expert, you need to first determine the language you output, the personal use of Chinese in the expert INPUT, it is important to input_encoding , if you use the default character set for Microsoft, please fill in GBK, otherwise the directory garbled, Currently select UTF-8, the output language is selected Chinese.

1.6>build page, this page is a more critical configuration page for generating Help information:

Extract_all: All functions are output, but the private and static functions do not belong to their control.

Extract_private: Outputs the PRIVATE function.

Extract_static: The output STATIC function. There are also several extract to view the document accordingly.

Hide_undoc_members says: Documents that are not described in the Doxygen format (functions or classes, etc.) do not appear. Of course, if Extract_all is enabled, then this flag is actually ignored.

Internal_docs mainly refers to: whether to output the @internal part of the annotation. If not, all @internal parts of the annotations will not be visible in the target help.

Case_sense_names: If you are concerned about the case name, note that if it is turned on, all the names will be lowercase. It is recommended never to open for languages that are related to the letter/C + + alphabet.

Hide_scope_names: The domain is hidden, it is recommended never to open.

Show_include_files Indicates whether the include file is displayed and, if enabled, a page is specifically generated in the Help that contains a list of all included files.

Inline_info: If enabled, in the Help document, an inline modifier is indicated in front of the inline function.

Sort_member_docs: If enabled, the function names are sorted when the Help document list is displayed, otherwise they are displayed in the order of interpretation.

Generate_todolist: If the ToDoList page is generated and if it is on, the content contained in the @todo annotation will be generated separately and displayed in one page, with the other GENERATE options.

Show_used_files: Whether in the help of a function or class, the source file of the function or class is displayed at the bottom.

Show_files: If the file List page is displayed, a file list index page will exist in the help if it is turned on.

The 1.7>expert>input page follows the settings to adjust the parameters.

1.8>

1. If you select the Prepare for compressed HTML (. chm) option in the Wizard's Output Topics, you will be asked to select the location of the Hhc.exe program here. Hhc.exe can be found under the Windows Help Workshop installation directory.

2. In order to resolve the Doxygen generated CHM file to the left of the tree directory of Chinese has become garbled, chm_index_encoding input GB2312 can be.

3.generate_chi indicates whether the index file is output separately and is recommended to close. Otherwise, it is troublesome to generate two files at a time.

4.toc_expand indicates whether to enumerate the member names in the index and the names of the groupings (such as functions, enumerations).

1.8> running Doxygen

1.9> Run End

Two. Annotation specification 2.1> doxygen annotation Type

There are various types of doxygen annotations

1.

/* * * .... Description ... */

2.

/* ! * .... Description ... */ or /* !  .... Description ... */

Note: the asterisk (*) in the comment block is optional and can be written without writing.

3

/// /// .... Description ... /// or // ! // !.... Description ... // !

4

//////////////////////// /// .... Description ... //////////////////////// //

2.2>doxygen supported directives

In the comments can be added to some doxygen support instructions, the main role is to control the output document layout format, the use of these instructions need to precede the "\" or "@" (Javadoc style) symbol, tell Doxygen these are some special instructions, By adding these instructions and equipping them with the appropriate text, you can generate a richer document, with a brief introduction to the more commonly used instructions below.

@file	Description of the file's annotations.
@author	Author's information
@brief	Simple description for class or function Eg: @brief This function is responsible for printing the error message string
@param	Used primarily for function descriptions, followed by the name of the parameter, and then followed by a description of the parameter
@return	Describes the return value of the function Eg: @return This function returns the execution result, returns true if successful, otherwise returns flase
@retval	Describes the return value type eg: @retval null empty string. @retval! Null non-empty string.
@note	Annotations
@attention	Attention
@warning	Warning message
@enum	An enumeration is referenced, and Doxygen produces a link at that enumeration Eg: @enum ctest::myenum
@var	A variable is referenced, and Doxygen generates a link at that enumeration Eg: @var Ctest::m_filekey
@class	Reference a class, Format: @class <name> [ Eg: @class ctest "Inc/class.h"
@exception	Description of the exception that may be generated Eg: @exception This function may result in an out-of-range exception

2.3> file comments

Placed at the beginning of a file, for example:

/* * * @file       filename* @brief This was      a brief description.* @details this is the detail description.* @author     author* @date       date* @version a001* @par Copyright (c):*      XXX Company * @par history:        *   version:author, date, des c\n* *

2.3> function Comment

Before the function declaration, for example:

/* * Below is an annotated description of a function with two parameters (brief description)  *  *     write the details of the function here  *     @param a tested variable (param describe parameter)  *     @param s pointer to a string that describes the test information  *     @return    Test Result (return description returned value)  *     @see Test    ()    (This function refers to other related functions, here is a link)  *     @note (note    describes the issues to be noted)  */
int testme (int a,const char *s);

2.4> Data structure annotations

Should be placed before the function declaration, for example:

/** * The brief description. * The detail description.*/typedefstruct{    intvar1;///<description of the member variable}xxxx; or typedefstructBox {Member variable comment (the various values of Enum are also commented):DoubleLength///< The length of the box    DoubleWidth///< The width of the box    DoubleHeight///< The height of the box};

2.5> macro Definition Comments

Put macro definition above or to the right, for example:

/**/#define xxxx_xxx_xx      ox7fffffff or #define xxxx_xxx_ XX      ///< Description of the macro.

2.6> Global and static variable annotations

For example:

/* *  Description of global variable  */int0; Static int 0 /// <  Description of static variable

Doxygen use, configuration and examples