Is Code Write comments are always the majority Program Personnel have some troubles. 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 comments to the corresponding code when writing or modifying the 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. There are many open-source projects (including the first two Article The log4cpp and cppunit mentioned in this article both 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
Doxygen installation is very simple. in Linux, you can directly download the installation package and run it. Source code Compilation and installation are also common compilation and installation commands. 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 the program structure, for example: file, class, structure, function, variable, Macro, and other comments, and 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 explicitly specifies the files to be ignored in the input directory, for example, fromout *. cppoutput_language: the language of the document generated in English. Currently, two or 30 languages are supported. Chinese users can set it to Chinese.
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 xml format document 3. doxygen comment
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. 2) multi-line comments of the QT style. 3 )///... Text ....
4 )//! ... Text ....
There are multiple identification methods for brief description. Here we recommend that you use the @ brief command to force the description. For example, the above annotation format is used to annotate 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;
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: int func1 (int A, int B). During design, there is usually a module concept. A module may contain multiple classes or functions, A collection of code that completes 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. The code in codegroup 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. 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:
// @ {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 ://@{
Code...
// @} 3.3 common 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. 4. Writing comments
How to write comments, write more or write less. Too many comments may even interfere with code reading. One general principle of writing comments is that comments should be used to indicate the author's intention, at least to summarize some code, rather than repeating or interpreting the code. The code that repeats or explains the code may be easier to understand. The purpose of reflecting the author's intention to annotate and interpret code generation is to annotate the problem solving level, while the Code summative annotation is to annotate the problem at the answer level. The recommended process of writing comments is to first use comments to outline the main framework of the code, and then write the corresponding code according to the comments. Comment out the main data structures, output functions, and variables common to multiple functions in detail. Comments the control structure and single-purpose statement set in the code. The following are some important points to note when writing comments:
Avoid comments on separate statements;
By commenting on why, or what to do, the code reader can only read and understand the code;
Comment on areas where readers may have doubts;
Comment on the data definition, rather than the usage process;
Rewrite codes that are hard to understand, instead of trying to explain them through annotations;
Comment out key control structures;
Comment on data and function boundaries and usage premises; 5. References
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 to doxygen
Http://www.stack.nl /~ Dimitri/doxygen/doxygen_intro_cn.html5. 10 minutes to document your code
Http://www.codeproject.com/tips/doxysetup.asp6. Use doxygen
Http://www.csdn.net/Develop/article/16%5C16383.shtm
This article is from the csdn blog. |
|
