Convenient development documentation - DOXYGENMOUNTON @ {www.ihere.org} (mount0n@yahoo.com) August 2003
0. The preface to code write comments has always been a matter of most programmers. Both the programmer can accept the maintenanceability and readability encoding of the program, but what is the problem should be written to the comments, how to write, how much to write, write, etc., many programmers still have no answer. More headaches are written documents, as well as maintenance of documents, developers can usually have to write or modify the corresponding annotations when writing or modifying code, but then need to fix the corresponding document is more difficult. If you can directly convert it directly into a document, it is undoubtedly a gospel for developers. Doxygen automatically converts the annotations of some format to the corresponding documentation.
Doxygen is a GPL-based open source project, which is a very good document system that currently supports most UNIX (including Linux), Windows families, Mac systems, fully supports C , C, Java, IDL (CORBA and Microsoft Family) Language, partly supports PHP and C # languages, and the output formats include HTML, LATEX, RTF, PS, PDF, compressed HTML and UNIX MANPAGE. There are many open source projects (Log4CPP and CPPUnit, including the first two articles), have used the Doxygen document system. The domestic developers have not used this tool, here to introduce this tool from the perspective of developers, so that developers can master this technology as soon as possible, and combine this tool to explore how to write annotations. The following is described as an example with the C language under Linux. The following discussion is based on DoxyGen 1.3.3.
1. Doxygen use steps because it is just the use of tools, this does not introduce its principle, starting from the use steps. Doxygen's use steps are very simple. It can be divided into: 1) The first time you need to install DOXYGEN program 2) Generate DoxYgen Profile 3) When encoding, write a comment in some format 4) Generate the corresponding document Doxygen installation is very simple, Linux can download and install The package is running, downloading the source code compilation and installation is also a relatively universal compilation installation command. Please refer to its installation document to complete the installation.
Doxygen can define project properties and many options during the documentation, using the following command to generate a default configuration file: doxygen -g [configuration file name] can modify the configuration file according to the specific needs of the project The specific modification process is described below. Modified profiles can be used as a template for future projects.
Let Doxygen automatically generate documents, the usual annotation style can not follow Doxygen's own format. Specifically how to write DOXYGEN's annotations in Section 3 in detail.
OK, the code is completed, the comment is written according to the format, how is the last document? Very simple, run the following command, the corresponding document will be generated in the specified directory. Doxygen [configuration file name]
It should be noted that Doxygen does not address all annotations, Doxygen's key attention to annotations related to program structure, such as files, classes, structures, functions, variables, macros, etc., and ignore the comments of variables, code, and so on.
2. Doxygen Profile Doxygen Profile The format is also the format of the usual UNIX configuration file: Note '#' Start; tag = value [, value2 ...]; Tag = Value [, Value2 for multiple values ...].
The modification of Doxygen's profile is divided into two categories: one is the output option, how to explain the source code, how to output; one is the project-related information, such as project name, source code directory, output document directory, etc. For the first setting, usually all items can share a configuration, and the latter is that each item must be set. The following options are important to explain the options that you need to modify, and other options have a detailed explanation in the configuration file.
TAG Default Meaning Project_name Project Name Project_number Project Name Project_Number You can understand the directory of the version information Output_directory output file, relative to the directory (Doxygen Run Directory) or an absolute directory INPUT code file or code where the code is located, using space split file_patterns * .c * .cc * .cxx * .cpp * .c * .java * .ii * .ix * .ipp * .i * .inl * .h * .hh * .hxx * .hpp * .h * .idl * .odl specified INPUT Specific files in the directory, such as: *. CPP * .c * .h recursive no recursively recursively in the subdirector of the directory Exclude Exclude in the Input directory Exclude_patterns clearly specified in the input directory, if you need to ignore files, such as : Fromout * .cpp output_language english generates the language of the document, currently supports 2,30 languages, domestic users can set to chineseUse_windows_encoding Yes (WIN version) No (UNIX version) encoding format, can be default. Extract_all no is NO, only explains the code with Doxygen format annotation; for YES, parsing all code, even if there is no comment. Class private member and all static items by extract_private and extract_static control Extract_private no parsing whether eXtract_static no parsing whether static item extract_local_classes YES Whether to resolve the class Source_Browser No, if you are Yes, source code The file will be included in the document inline_sources if the implementation code for Yes, functions, and classes is included in the document alphabetical_index no generate a list of alphabetic_index no, there are many classes, structural and other items, it is recommended to set it to Yesgenerate_html Yes to generate HTML format Document generate_htmlhelp no Generates Compressed HTML Format Document (.CHM) Generate_Latex YES Whether to Route Latex Format The generation_rtf No Generates the RTF format Document generate_man no Generates the MAN Format Document Generate_XML NO to Generate XML Format Documents
3. Doxygen Note 3.1 Notes The following is the largest part of the workload, and the Doxygen format is written. Usually the code can be attached to an annotation block to interpret the code, and an comment block consists of one line or more lines. Typically a comment block includes a brief description (Brief) and a detailed description (Detailed), which are optional. There are a variety of ways to identify DOXYGEN identifiable comment blocks. 1) Multi-line annotations of Javadoc types. / ** * ... .text .... * / 2) Multi-line comments in QT style. / * / 3) /// ... text ... .4) //! ... text .... Brief description has a variety of ways, here is recommended to use the @Brief command to force instructions, for example: / ** * @Brief [Some Brief Description] * [BRIEF Description More.] * * [Some More Detailed Description ...] * / The above comments format is used to comment on the code immediately after. Doxygen also allows the annotation to release the code, and the specific format is to put one '<' to the beginning of the comment. For example: int var1; / ** <... .Text .... * / Int var2; /// <... .text .... 注释 and code is completely separated, put it in other places, but also need to use special commands plus Names or statements identify, such as Class, Struct, Union, Enum, Fn, Var, DEF, FILE, NAMESPACE, PACKAGE, INTERFACE (these are the annotations of Doxygen Follows). It is not recommended here, it is recommended that the comments are as good as possible to place before and after the code. See the Doxygen Manual for specific use.
3.2 DOXYGEN Common Note Format The usual selection The above, two comment style, encounter various types definitions, key variables, macros in the header file, definitely clear it in prior or after using @brief, continue Write a detailed note.
The annotation of the function is a part that often needs to be annotated. In addition to defining its brief description and detailed comments, you can also use the param command to annotate each parameter, and annotate the return value using the return command. Common formats are as follows: / ** * @ brief Func's brief comment. * * Some detaild comment. * @ Param A [param A 's comment.] * @ Param b [param b' s comment.] * @ Exception std: : OUT_OF_RANGE [Exception's Comment.] * @ Return [Return's Comment.] * / INT FUNC1 (Int A, INT B);
When designing, there is usually the concept of modules, one module may have multiple classes or functions, completing a collection of code for a particular function. How to comment about this concept? Doxygen offers the concept of Group, and the annotation of the generated module will be placed separately in a module page. Use the following format to define a group. / ** [group_name] * Detailed group description] * @ {* / code / ** @} * / group code can have its own comment. Simply define a module, remove the {and} commands. Any other code item (such as class, functions, or even files) If you want to join a module, you can use the ingroup command in its Doxygen annotation. Use the ingroup command between groups to form a tree relationship. / ** @file util.cpp * @ingroup [group_name] * @Brief File's brief info. * / Add multiple code items to a module can be used in a module. You can use the addtogroup command, format, and defgroup. For code items such as class, functions, variables, such as class, functions, variables), etc. for a certain function, if you want to add a comment together, and don't want to upgrade to the concept of the module, you can pass the following method: @ {/ ** Comments for all Below code. * / code ... // @} Naming this group can use the name command. At this point, the middle code can have its own comment. Such as: / ** @name group_name * description for group. * @ @ {Code ... @}
3.3 Doxygen Common Note Commands Doxygen requires annotations that require special processes in the annotation of the comment, such as the parameters of the function, and return values. The above also mentioned some comment commands (such as: brief, param, return, and group-related commands), explain other commonly used annotations commands. @Exception
As so far as, the commonly used Doxygen's annotation is discussed, we can write a notes for Doxygen understanding in a certain format, and can use Doxygen to make the corresponding document, but what should be written in the comment, how to write a valid annotation It may be a deeper problem that plagues developers.
4. What should I write about the writing of the comment, and write more. Excessive annotations even interfere with reading of the code. One of the general principles written is that comments should be used as much as possible to indicate the author's intent, at least a summary of a part of the code, and should not be repeated or explained to the code. Repeat or interpretation of code for code, seeing code may be more easily understood. Referring to the purpose of the comment of the author's intent, comment from the level of solving the problem, and the code summary annotation is annotated from the hierarchy of the problem. Recommended write comments The process is first using comments outlined the main framework, and then writes the corresponding code according to the comment. For various main data structures, the output functions, the variables commonly used in multiple functions are detailed. Comment on the code in the code, a single destination statement set. Here are some points that you need to pay attention to when writing comments: avoid comments for individual statements; explain why this is done, or what to do, make the code reader can only read the annotation code; Note; annotate the data definition instead of annotation of its use; rewriting for the code that is difficult to understand, not to try to explain the critical control structure; the boundary of the data and functions, use Premise, etc.
5. Reference 1. Doxygen HomePage http://www.stack.nl/~dimitri/doxygen/
2. Doxygen Manual http://www.stack.nl/~dimitri/doxygen/manual.html
3. Code Complete: A Practical Handbook of Software Construction. Redmond, Wa .: Microsoft Press, 880 Pages, 1993. ISBN: 1-55615-484-4. 4. Introduction Doxygen http://www.stack.nl/~ Dimitri / doxygen / doxygen_intro_cn.html 5. 10 minutes to Document your code http://www.codeproject.com/tips/doxysetup.asp
6. Use doxygen http://www.9cbs.net/develop/Article/16\16383.SHTM
6. About the author mounton @ {www.ihere.org} The current development, research; software development process of network security products; You can contact him via mount0n@yahoo.com.
