C/C ++ document annotator-common knowledge of Doxygen (Continuous updates)

What is Doxygen?

Doxygen

Is an open-source cross-platform documentation system that is similar to JavaDoc. It fully supports C, C ++, Java, Objective-C, and IDL languages.
Some support PHP and C #. The annotation syntax is compatible with Qt-Doc, KDoc, and JavaDoc. Doxgen can generate an online class in HTML format from a set of archive source files
Browser, or offline LATEX, RTF reference manual. For Unarchived source files, you can also configure Doxygen to extract the code structure. Or use the automatically generated include Dependency Graph
(Include dependency graphs), inheritance graph (inheritance divisor), and collaboration Graph
Digoal) to visualize the relationship between documents. The formats of help documents generated by Doxygen can be CHM, RTF, PostScript, PDF, HTML, and Unix.
Man pages, etc,





It also supports the generation of mathematical formulas.

Doxygen is developed on Linux but can also be run on other Unix platforms. In addition, there are executable versions on Windows 9x/NT.

Doxygen uses many third-party information generation tools based on compilation to help generate more eye-catching documents. For example, you can embed a formula that complies with the tex Standard in the annotations, and Doxygen helps you to display the formula to your documents. You can also automatically generate an inherited graph and compose a graph for your documents, UML format diagram, as long as you put Graphviz
Installation
And open the relevant parameters. What's more, with the dot method of Graphviz, you can write the drawing instructions in the correct format in the comments. The scenario diagram, architecture diagram, flow diagram, InterAction diagram, and next door
As long as you can draw from Graphviz, Doxygen can help you. If you want to change the legend, you can change it, and you can live a happy life. The g9 boss has recommended Graphviz.
Pass
Again, more good words will look pale. This is undoubtedly a good thing and a mess of convenience. For programmers who have been dealing with code all the year round, this is undoubtedly a must for home-based travel and murder
Fruit knife.

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.

 

 

Annotation writing

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
The intent should at least be a summary of a part of the code, instead of repeating or interpreting the code. The code that repeats or explains the code may be easier to understand. Annotation interpretation generation that reflects the author's intention
The purpose of the code is to make comments at the problem solving level, while the Code summative comments are comments at the Question Answering 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;

 

 

If you are a mentally retarded user just like me, modify the following:

1.  
   • PROJECT_NAME: write down the name you want
     
   • OUTPUT_DIRECTORY: Output Folder. I use ~ /Desktop/Floorplan
     
   • CREATE_SUBDIRS: changed to YES
     
   • EXTRACT_ALL: changed to YES
     
   • SHOW_DIRECTORIES: changed to YES
     
   • FILE_PATTERNS: Generally, you do not need to change it. *. c *. h *. cpp *. hpp will be automatically included.
     
   • RECURSIVE: change to YES. You certainly want to include the source code in those subfolders.
     
   • SOURCE_BROWSER: YES
     
   • __Hyperlinks: YES
     
   • USE_PDFLATEX: YES
     
     

How to Use 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.