[Original] Use doxygen to manage project documents or comments, doxygen project_PHP tutorial

[Original] Use doxygen to manage project documents or comments, doxygen project

1. Doxygen application scenarios:

Doxygen can be used to manage comments in current mainstream programming languages ​​to form a documentation system. (Including C, C++, C#, Objective-C, IDL, Java, VHDL, PHP, Python, Tcl, Fortran, etc.). Doxygen official website address (http://www.doxygen.nl/) Recently, most of the time is spent on the maintenance of the API interface. One of the more important aspects is how the interface you write allows the caller to understand the usage at a glance. It is the same whether it is the cooperation between the internal wireless server and the client or the API interface open to the outside world. After spending a few days trying to use doxygen combined with svn hook to manage interface documents, it is very convenient and practical. The doxygen official website itself actually uses doxygen. If you want to see more specific effects, you can directly refer to http://www.doxygen.nl/.

Below I will post some of the renderings I made myself. The UI is very frustrating. When you actually use it, you can ask the company's UI department to beautify it. Since I mainly use it on the intranet, I haven't thought too much about the UI experience. :

2. Installation:

Doxygen currently fully supports mainstream systems such as windows, mac ox, and linux. And it is basically used in all current mainstream programming languages. Here is a brief introduction to the source code compilation and installation process under the ubuntu system. For other installation methods, please refer to the official website.

3. Configuration of the configuration file using doxygen:

The use of doxygen can be said to be the configuration of the configuration file. That is to say, you only need to slightly configure the configuration file and then execute the command: xxxx/doxygen xxxx.conf to generate the document you want (Here doxygen provides documents in a variety of formats. I mainly use html, so that we can configure a web service on this html ourselves, and then use the document on the web. ), doxygen provides it. With more than 200 configuration items, rich functions can be completed through configuration files. Here are some commonly used configuration instructions:

• Use the command xxx/doxygen -g to generate a default configuration file doxygen.conf in the current directory. Open the default configuration file, and you will find that each configuration item in it is in the key-value format of configuration name and configuration value . If you have a certain knowledge of English, configuration is basically not a problem.
• For detailed configuration instructions, please refer to: http://www.stack.nl/~dimitri/doxygen/manual/config.html
• ABBREVIATE_BRIEF                                                                                                                                                                                                                         Aliases // Alias ​​
• ALLEXTERNALS                                                                                                                                                             // All external documents
• ALPHABETICAL_INDEX //Alphabetical index
• ALWAYS_DETAILED_SEC        //Detailed description part
• BINARY_TOC                                                                                                                                                                                                                                                 // Binary operations
• BRIEF_MEMBER_DESC                                                                                     // Short member description CALL_GRAPH                                                                                                                                                                                                                                                                            
• CASE_SENSE_NAMES //The names of the detected examples
• CHM_FILE                                                                                                                                                                                                                                                         //CHM format file
• CLASS_DIAGRAMS                                                                                           // Class-Table
• CLASS_GRAPH       //Class-Graph
• DOT_PATH        //DOT path settings
DOT_TRANSPARENT
•      //DOT conversion settings
DOTFILE_DIRS
•                                                                                                                                                                                                                                     //DOTFILE list display
ENABLE_PREPROCESSING
•  ​                                                                                                                                                                                                          //Allow the "preprocessing" directive
ENUM_VALUES_PER_LINE
• //The enumeration value of each line
ENABLED_SECTIONS
•                                                                                                                                                                                                        Example_patterns // The file format ( *.cpp, *.h, *.java, etc.)
• EXAMPLE_RECURSIVE     //Example recursion
• COLLABORATION_GRAPH                                                                                                                                                                                 
• COLS_IN_ALPHA_INDEX                                                                                                                                                                                                                                                   COMPACT_LATEX
//Compressed LATEX document
• COMPACT_RTF
//Compressed RTF document
• CREATE_SUBDIRS
                                            //Create a "subdirectory"
• DETAILS_AT_TOP
//Detailed header of the document
• DIRECTORY_GRAPH
                                                                                              
• DISABLE_INDEX                                                                                                
• DISTRIBUTE_GROUP_DOC                                                                                                                                                  EXCLUDE
                                                                                                                                                                                             
• EXCLUDE_PATTERNS                   //Executable file format (*.exe, *.dll, etc.)
• EXCLUDE_SYMLINKS     //Executable SYMLINKS
• EXTERNAL_GROUPS     //External files used
• EXTRA_PACKAGES                                                                                                                                                                                                                                               // External plug-in packages used
• EXTRACT_ALL                                                                                     
• EXTRACT_LOCAL_CLASSES //Extract all local classes
• EXTRACT_LOCAL_METHODS //Extract all local methods
• EXTRACT_PRIVATE                                                                                            EXTRACT_STATIC
                                                                                                                               // Extract all static
• FILE_PATTERNS                                                                                                                                
• FILTER_PATTERNS                             //Control format (main version: 1st version: 2nd version number)
• FILTER_SOURCE_FILES //Version control of original files
• FULL_PATH_NAMES //Full path name
• GENERATE_AUTOGEN_DEF //Generate automatic definition file format
• GENERATE_BUGLIST //Generate BUG list
• GENERATE_CHI                                                                                                                                 GENERATE_DEPRECIATELIST
//Generate the "evaluation" list
• GENERATE_HTML
//Generate HTML
• GENERATE_HTMLHELP
//Generate HTMLHELP
• GENERATE_LATEX
//Generate LATEX
• GENERATE_LEGEND
//Generate legend
• GENERATE_MAN
                                                          // Generate MAN file
• GENERATE_PERLMOD
//Generate Perl script
• GENERATE_RTF
//Generate RTF
• GENERATE_TAGFILE                                                                                                                                                                                                        
• GENERATE_TESTLIST //Generate TESTLIST
• GENERATE_TODOLIST //Generate TODOLIST
• GENERATE_TREEVIEW //Generate tree view display
• GENERATE_XML //Generate XML
• GRAPHICAL_HIERARCHY //Inherit chart
• GROUP_GRAPHS                                                                                               HAVE_DOT
                                                                                                                 
• HIDE_FRIEND_COMPOUNDS //Hide the "composite" friend type
• HIDE_IN_BODY_DOCS //Hide the body of the document
• HIDE_SCOPE_NAMES //Hide the "scope" name
• HIDE_UNDOC_CLASSES //Hide all "unarchived" CLASS
• HIDE_UNDOC_MEMBERS //Hide all "unarchived" members
• HIDE_UNDOC_RELATIONS //Hide "unarchived" relationships
• HTML_ALIGN_MEMBERS //Member alignment in HTML document
• HTML_FOOTER //HTML footnote settings
• HTML_HEADER //HTML header settings
• HTML_OUTPUT                                                                                                                                                                                                                    
• HTML_STYLESHEET //HTML style setting
• IGNORE_PREFIX                                                                                                                                                                                 Image_path // The path of the picture set
• INCLUDE_GRAPH                                                                                            ​
• INCLUDE_PATH                                                                                                                                                                                                                                                              
INHERIT_DOCS
• //Inheritance relationship of documents
INLINE_INHERITED_MEMB
• //Inline members obtained through "inheritance"
INLINE_SOURCES
• //Source code of the inline part
INPUT
•                                                                                                      ​  INPUT_FILTER                                                                                                                                                                                           // Acceptable input file extension format settings (important)
• INTERNAL_DOCS //Internal Documents
• JAVADOC_AUTOBRIEF                                                                          // "Automatic summary" of the document generated by the JAVADOC tool
• LATEX_BATCHMODE //LATEX matching mode
• LATEX_CMD_NAME                                                                              // LATEX command name
• LATEX_HEADER                                                                                                 LATEX_HIDE_INDICES
                                                                                                                                                                                                       
• LATEX_OUTPUT                                                                                               
• MACRO_EXPANSION //Macro expansion settings (important)
• MAKEINDEX_CMD_NAME //MAKEINDEX command index
• MAN_LINKS                                                                                                                                                                                                                                                                                MAN_OUTPUT
                                                                                                                                                                                                                                                  
• MAX_DOT_GRAPH_DEPTH //Maximum depth of DOT map
• MAX_DOT_GRAPH_HEIGHT //Maximum height of DOT graph
• MAX_DOT_GRAPH_WIDTH //Maximum width of DOT graph
• MAX_INITIALIZER_LINES //Maximum initialization lines
• MULTILINE_CPP_IS_BRIEF //Short description of multiple CPP files
• MULTILINE_CPP_IS_BRIEF //Short description of multiple CPP files
• OPTIMIZE_OUTPUT_FOR_C //Optimization settings for C
• OPTIMIZE_OUTPUT_JAVA //Optimization settings for JAVA
• OUTPUT_DIRECTORY //Output path setting (important)
• OUTPUT_LANGUAGE //Output language setting (important)
• PAPER_TYPE                                                                                                                                                                                                                                    
• PDF_HYPERLINKS //PDF format hyperlink settings (important)
• PERL_PATH                                                                                                                                                                                                                             PERLMOD_LATEX
                           //perlmod LATEX
• PERLMOD_MAKEVAR_PREFIX
//perlmod MAKE file version PREFIX
• PREDEFINED
                                                                                                                                                                                                                                                                              
• PROJECT_NAME                                                                                                                                                                                                                                            
• PROJECT_NUMBER //Project members (important)
• QUIET                                                                                                                                                                                                                                                                               .
• RECURSIVE                                                                                                                                                             
• REFERENCED_BY_RELATION //Cross reference (important)
Repeat_brief
• // Set up "Short Explanation" to open the state
RTF_HYPERLINKS
•                                                                                               RTF_OUTPUT                                                                                                                               
• SEARCH_INCLUDES                                                                                                                                                                    // What needs to be included in the search (important)
• SEARCHENGINE                                                                         //Search engine settings (important)
• SHORT_NAMES                                                                                                                                                                                                                                                         
SHOW_DIRECTORIES
• //Show directory
SHOW_INCLUDE_FILES
•                                                                                                                                               // Show included files (usually NO, otherwise too large) Show_used_files
// Show the file (general yes)
• SKIP_FUNCTION_MACROS
                        // Skip the macros in the function (important), novices should not skip it
• SORT_MEMBER_DOCS
                                                                                                                                                                                                                                    
• SOURCE_BROWSER                                                                                                                                                                                                                       
• STRIP_CODE_COMMENTS //Exclude which barcode form comments (important)
• STRIP_FROM_INC_PATH                                 // Exclude which header files contain comments (important)
• STRIP_FROM_PATH //Exclude which barcode path settings
• SUBGROUPING                                                                                                                                                                                                                                     // Subgroup settings (important)
• TAB_SIZE                                                                                                                                                                                                                TAGFILES
                                                                                                                                                                                    
• TEMPLATE_RELATIONS //Template relationship settings (important)
• TOC_EXPAND                                                                                                             
• TREEVIEW_WIDTH                                                                                                                                                         UML_LOOK
                                                                                                                                        
• USE_WINDOWS_ENCODING //Use the encoding form of the windows system (important)
• VERBATIM_HEADERS //VERBATIM headers (header files)
• WARN_FORMAT                                                                                                                                                                                                           // Warning format specification (important)
• WARN_IF_DOC_EC_ERROR // If the document is wrong, a warning
• WARN_IF_UNDOCUMENTED //If it is an unarchived file, display a warning
• WARN_LOGFILE                                                                                                                                                                                                                       // Warning log file settings
• WARN_NO_PARAMDOC                                                                                                                                                  // No parameter document warning format setting
• WARNINGS                                                                                                                                                                                                                                                                               ​
XML_DTD
•                                                                                                                                                                                                                                      XML_OUTPUT                                                                                                                                                                                                                            
• XML_PROGRAMLISTING                                                         //XML program list (important)
• XML_SCHEMA                                                                                                                                                                                                                                           4. Writing comments after doxygen configuration is completed
• After you configure doxygen, you will basically spend your time writing and maintaining comments in your code. I want to use doxygen to manage documents. Then code comments do not need to be strictly required.

  After writing comments according to the specifications, the effect displayed in the page document is as follows:

/**
 * @brief 这里用brief来说明接口方法的主要功能
 * @date   接口方法的创建时间
 * @author 接口方法的创建人
 * @param  : 参数说明如下表：
 * name     | type     |description of param 
 * ----------|-----------|--------------------
 * car_id   | int      |车源编号
 * province | int      |业务员所在省份
 * x        |  x       |   x
 * x        |  x       |   x
 * x        |  x       |   x
 * @return    返回值说明如下：
 * name     | type     | description of value
 * -------- |----------|----------------------
 * car_id   | int      | 车源编号
 * car_info | object   | json对象格式的车源信息
 * @warning   该接口需要告知给调用者看的一些警告
 * @attention 该接口需要告知给调用者看的一些注意事项
 * @note      该接口的一些备注说明。通常用于当后者对该接口有较大改动的时候。备注一下某个时间点某人改动了什么东西
 * @ todo     该接口的一些未完成的待办内容
 */
public function newSale() {
    do someting;
 }

The writing rules can be agreed in advance within the project, and the rest only needs to be maintained according to these rules. Of course, people are human after all, and it is impossible to guarantee that all code can be written according to the expected annotation rules. Therefore, the path to the log file can be specified in the doxygen configuration file. You can make good use of this log file, write a small piece of code in the corresponding script language to analyze the log file, and then display it on the web page in a humane way. Designated managers regularly check the annotation error log and correct incorrect annotation content immediately.
5. Commonly used features of doxygen

The functions of doxygen are far more than what I introduced above, and there are many rich and colorful functions. If you want to use this thing, you can go to the doxygen official website to learn about it yourself. This article may be reproduced at will, but please be sure to indicate the source of the original text.

http://www.bkjia.com/PHPjc/922301.html

www.bkjia.comtrue

http: //www.bkjia.com/PHPjc/922301.htmlTechArticle

[Original] Use doxygen to manage project documents or comments, doxygen project 1, doxygen application scenarios: doxygen can be used Manage the comments of current mainstream programming languages ​​to form a documentation system...