Convenient development documentation tool-doxygen

0. Preface Writing comments for code has always been a problem for most programmers. Currently, programmers can all accept comments for program maintainability and readability encoding, but such questions include where to write comments, how to write comments, and how much to write, many programmers still have no answer. The biggest headache is the writing and maintenance of documents. developers can usually endure the need to write or modify the corresponding comments when writing or modifying code, however, it is difficult to modify the relevant documents. If you can directly convert a comment into a document, it is undoubtedly a blessing for developers. Doxygen can automatically convert comments in a certain format into corresponding documents. Doxygen is a GPL-based open-source project and is a very good documentation system. It currently supports running on most Unix (including Linux), windows, and MAC systems, and fully supports C ++, c, Java, IDL (the CORBA and Microsoft families) languages, some support PHP and C # languages, the output formats include HTML, latex, RTF, PS, PDF, compressed HTML, and Unix manpage. Many open-source projects (including log4cpp and cppunit introduced in the previous two articles) use the doxygen document system. There are not many developers in China. Here we will introduce this tool from the perspective of developers, so that developers can grasp this technology at the minimum cost as soon as possible, this tool is used to discuss how to write comments. The following uses the C ++ language in Linux as an example to describe how to use doxygen1.3.3. 1. Steps for using doxygen Because it is only a tool, the principle of this tool is not described here, it starts directly from the steps of use. Doxygen is easy to use. It can be divided: 1) The first time you use a program that requires doxygen Installation 2) generate the doxygen configuration file 3) write comments in a certain format during encoding 4) generate the corresponding document The installation of doxygen is very simple. in Linux, you can directly download the installation package and run it. the download of source code compilation and installation is also a common compilation and installation command. See the installation documentation to complete the installation. Doxygen can define project properties and many options during document generation when generating documents. Use the following command to generate a default configuration file: Doxygen-G [configuration file name] You can modify the corresponding items in the configuration file according to the specific needs of the project. The specific modification process is described below. The modified configuration file can be used as a template for future projects. To enable doxygen to generate documents automatically, the standard annotation style is not acceptable. You must follow the doxygen format. For more information about how to write comments for doxygen, see section 3rd. OK. After the code is compiled, the comments are also written in the format. What is the final document? It is very simple. Run the following command and the corresponding documents will be generated in the specified directory. Doxygen [configuration file name] Note that doxygen does not process all comments. doxygen focuses on comments related to program structures, such as comments such as files, classes, structures, functions, variables, and macros, ignore comments of variable and code in the function. 2. doxygen configuration file The format of the doxygen configuration file is also the format of the Common Unix configuration file: Comment '#'; tag = value [, value2…]; You can use tag + = value [, value2…] for multi-value scenarios. Modifications to the doxygen configuration file are divided into two types: one is the output option, control how to explain the source code, and the other is the project-related information, for example, the project name, source code directory, and output document directory. After setting the first option, all projects can share one configuration, and the other is required for each project. Next, select the important option that may need to be modified for explanation. Other options are described in detail in the configuration file. Default Value of tag Project_name project name Project_number can be understood as version information. The directory to which the output_directory outputs the file. The relative directory (doxygen running directory) or absolute directory Input code file or code directory, separated by Spaces File_patterns *. C *. CC *. cxx *. CPP *. c ++ *. java *. II *. ixx *. IPP *. I ++ *. INL *. H *. HH *. hxx *. HPP *. h ++ *. IDL *. odl specifies a specific file in the input directory, for example :*. CPP *. C *. h Recursive no indicates whether to recursively input sub-directories in the directory The subdirectories that exclude needs to ignore in the input directory. Exclude_patterns specifies the objects to be ignored in the input directory, such as fromout *. cpp. Language of the document generated in output_language English. Currently, 2 or 30 languages are supported. Chinese can be set Use_windows_encoding Yes (WIN Version) No (Unix Version) encoding format, default. Extract_all no is no, and only codes with comments in doxygen format are interpreted. If yes, all codes are parsed even if no comments exist. The private members of the class and all static items are controlled by extract_private and extract_static. Extract_private no whether to resolve private members of the class Extract_static no whether to parse static items Extract_local_classes yes whether to parse the class defined in the source file (CPP file) If source_browser no is yes, the source code file will be included in the document. If inline_sources no is yes, the implementation code of functions and classes is included in the document. Alphabetical_index no generates a list of letters in alphabetical order. We recommend that you set it to yes when there are many classes and structures. Generate_html yes: whether to generate HTML documents Generate_htmlhelp no whether to generate compressed HTML format document (. CHM) Generate_latex yes: whether to use documents in latex format Generate_rtf No: whether to generate a document in the RTF Format Generate_man no whether to generate man-Format documents Generate_xml No: whether to generate a document in XML format

3. doxygen comments 3.1 annotation Style Below is the largest part of the workload. Install the doxygen format to write comments. Generally, a comment block can be attached to the Code to explain the code. A comment block consists of one or more lines. A comment block usually includes a brief description (brief) and a detailed description (detailed), both of which are optional. There are multiple ways to identify comments that can be recognized by doxygen. 1) javadoc-type multiline comments. /** *.... Text .... */ 2) multi-line comments of the QT style. /*! .... Text .... */ 3 )///... Text .... 4 )//! ... Text .... There are multiple identification methods. Here we recommend that you use the @ brief command to force the description, for example: /** * @ Brief [some brief description] * [Brief description more.] * * [Some more detailed description…] */ The preceding format is used to comment on the code that follows it. Doxygen also allows you to put comments behind the code. The specific format is to put a '<' to the start part of the comment. For example: Int var1;/** <.... Text .... */ Int var2; // <.... Text .... Annotations are completely separated from codes and can be stored elsewhere. However, special commands must be added with names or declarations for identification. For example: class, struct, union, Enum, FN, VAR, def, file, namespace, package, interface (these are the annotation types followed by doxygen ). It is not recommended here. It is recommended that you place comments before and after the code as much as possible. For more information, see the doxygen manual. 3.2 common doxygen comment formats In general, choose one or two annotation styles above. In the case of various types of definitions, key variables, and Macros in the header file, use @ brief to define its brief description before or after it, if you leave a blank line, continue to write its detailed comments. Comments to functions are often comments. In addition to defining its brief description and detailed comments, you can also use the param command to annotate its parameters and use the return command to annotate the return values. The common format is as follows: /** [Email = * @ brief] * @ Brief [/Email]Func's brief comment. * * Some detailed comment. [Email = * @ Param] * @ Param [/Email]A [Param A's comment.] [Email = * @ Param] * @ Param [/Email]B [Param B's comment.] [Email = * @ exception] * @ Exception [/Email]STD: out_of_range [Exception's comment.] [Email = * @ return] * @ Return [/Email][Return's comment.] */ Int func1 (int A, int B ); During design, there is usually a concept of a module. A module may contain multiple classes or functions to complete a set of code for a specific function. How to comment out this concept? Doxygen provides the group concept. Comments of the generated modules are placed on the page of a module separately. Use the following format to define a group. /** [Group_name] [brief group description] * Detailed group description] *@{ */ Code /**@}*/ The code in the group can have its own annotations. Define a module and remove the {And} commands. If you want to add any other code items (such as classes, functions, and even files) to a module, you can use the ingroup command in its doxygen comment. You can use the ingroup command between groups to form a tree-like relationship. /** @ File util. cpp * @ Ingroup [group_name] * @ Brief file's brief info. */ You can use the addtogroup command to add multiple code items to a module. The format is similar to defgroup. For code items (such as classes, functions, and variables) with similar functions, if you want to add comments together and do not want to promote them to the concept of modules, you can use the following method: //@{ /** Comments for all below code .*/ Code... //@} You can use the name command to name such a group. In this case, the intermediate code can have its own annotations. For example: /** @ Name group_name * Description for group. */ //@{ Code... //@} 3.3 doxygen comments Doxygen uses the annotation command to identify comments that require special processing in the annotation, such as function parameters and return values for highlighted display. Some annotation commands (such as brief, Param, return, and group-related commands) are also mentioned above, and some other commonly used annotation commands are explained below. @ Exception <exception-Object> {exception description} annotate an exception object. @ Warning {warning message} some precautions @ Todo {things to be done}: Comment on the things to be done @ See {comment with reference to other items} refers to comments that contain other part references. The comments include the names of other code items, and a reference link is automatically generated for them. @ Relates <Name> the annotation document for non-member functions is usually included in the class description document. @ Since {text} is usually used to describe the version and time from which code is written. @ Deprecated @ Pre {description of the precondition} describes the prerequisites for code items. @ Post {description of the postcondition} is used to describe the conditions for use after the code item. @ Code starts to describe a piece of code in the comment until the @ endcode command. The end of the code segment in the @ endcode comment. So far, the common doxygen annotation formats have been discussed. We can write comments recognized by doxygen according to certain formats, and use doxygen to generate corresponding documents conveniently and quickly, however, what should be written in comments, and how to write valid comments may be a deeper problem for developers.