Doxygen document generation tool

Posted by Mr_Mako on Wed, 16 Feb 2022 07:52:55 +0100

Doxygen code document generation tool

Doxygen

According to Baidu Encyclopedia, Doxygen is an open source, cross platform document system that supports C, C + +, Java and Objective-C languages. It can generate online HTML reference manuals or offline Latex and RTF reference manuals

Doxygen is a program file generation tool, which can convert specific comments in the program into instruction files.

For non archived source files, you can extract the code structure by configuring Doxygen
Dependency graphs can be generated
Can generate inheritance diagram, collaboration diagram, etc

Doxygen comments

The code annotation rules are as follows

External interface of the module, only in.h Note information is provided in
 Auxiliary functions inside the module, or private functions, are only available in the.c Retain comment information in

Function comments are generally

Function function
Entry parameters
Return value
matters needing attention
context

How does Doxygen distinguish between ordinary annotations and output annotations

For C, there are generally two kinds of C + + annotations

/**/

Doxygen by adding *, /,! As a special mark

/*
 * Normal comment
 */

Doxygen sets * or * after commenting the first *! As a sign, if these are detected,
The following comments will be interpreted as export documents

At the same time, the middle * sign can be omitted, like this

/**
   Comments to be output as documents
 */

 perhaps

/*!
   Comments to be output as documents
 */

How Doxygen extracts information from special annotations

Doxygen uses \ and @ as special markers. When a special marker is detected in the special annotation, it will then detect whether the following word is specified in advance by Doxygen. If so, the following annotation will be interpreted according to specific rules; If not, interpret \ and @ as plain text,

Is it stipulated in advance that you can view the documents on Doxygen's official website

vscode plugin

Doxygen Documentation Generator

In vscode, you can use plug-ins to quickly generate doxygen annotations

User setting in vscode The JSON plug-in is set as follows

{
    "window.zoomLevel": 0,
    "editor.minimap.enabled": false,
    "python.pythonPath": "C:\\Users\\jordan\\AppData\\Local\\Programs\\Python\\Python37\\python.exe",
    "workbench.iconTheme": "vscode-icons",
    "explorer.autoReveal": false,   //Cancel left auto focus
    "terminal.integrated.shell.windows": "D:\\Program Files\\Git\\bin\\bash.exe",
    "terminal.external.windowsExec": "D:\\Program Files\\Git\\bin\\bash.exe",
    "todo-tree.highlights.enabled": true,
 
    // Doxygen documentation generator set
    "doxdocgen.file.copyrightTag": [
        "@copyright Copyright (c) {year}  XX Communication company"
    ],
    "doxdocgen.file.customTag": [
        "@par Modify log:",
        "<table>",
        "<tr><th>Date       <th>Version <th>Author  <th>Description",
        "<tr><td>{date} <td>1.0     <td>wangh     <td>content",
        "</table>",
    ],
    "doxdocgen.file.fileOrder": [
        "file",
        "brief",
        "author",
        "version",
        "date",
        "empty",
        "copyright",
        "empty",
        "custom"
    ],
    "doxdocgen.file.fileTemplate": "@file {name}",
    "doxdocgen.file.versionTag": "@version 1.0",
    "doxdocgen.generic.authorEmail": "wanghuan3037@fiberhome.com",
    "doxdocgen.generic.authorName": "wangh",
    "doxdocgen.generic.authorTag": "@author {author} ({email})",
 
    "doxdocgen.generic.order": [
        "brief",
        "tparam",
        "param",
        "return"
    ],
    "doxdocgen.generic.paramTemplate": "@param{indent:8}{param}{indent:25}My Param doc",
    "doxdocgen.generic.returnTemplate": "@return {type} ",
    "doxdocgen.generic.splitCasingSmartText": true,
}

{
    // Doxygen documentation generator set
    // File notes: copyright information template
    "doxdocgen.file.copyrightTag": [
        "@copyright Copyright (c) {year}  XX Communication company"
    ],
    // File Comment: custom module. Here I add a modification log
    "doxdocgen.file.customTag": [
        "@par Modify log:",
        "<table>",
        "<tr><th>Date       <th>Version <th>Author  <th>Description",
        "<tr><td>{date} <td>1.0     <td>wangh     <td>content",
        "</table>",
    ],
    // Composition and sorting of file notes
    "doxdocgen.file.fileOrder": [
        "file",		// @file
        "brief",	// @brief introduction
        "author",	// author
        "version",	// edition
        "date",		// date
        "empty",	// Empty line
        "copyright",// copyright
        "empty",
        "custom"	// custom
    ],
    // Next, set the specific information of the above tag tag
    "doxdocgen.file.fileTemplate": "@file {name}",
    "doxdocgen.file.versionTag": "@version 1.0",
    "doxdocgen.generic.authorEmail": "wanghuan3037@fiberhome.com",
    "doxdocgen.generic.authorName": "wangh",
    "doxdocgen.generic.authorTag": "@author {author} ({email})",
    // Date format and template
    "doxdocgen.generic.dateFormat": "YYYY-MM-DD",
    "doxdocgen.generic.dateTemplate": "@date {date}",
	
    // According to the automatically generated annotation template (mainly reflected in function annotation at present)
    "doxdocgen.generic.order": [
        "brief",
        "tparam",
        "param",
        "return"
    ],
    "doxdocgen.generic.paramTemplate": "@param{indent:8}{param}{indent:25}My Param doc",
    "doxdocgen.generic.returnTemplate": "@return {type} ",
    "doxdocgen.generic.splitCasingSmartText": true,
}

Enter / * * in front of the function and press enter

/**
 * @brief 
 * @param  data             My Param doc
 * @param  left_1           My Param doc
 * @param  right_1          My Param doc
 * @param  left_2           My Param doc
 * @param  right_2          My Param doc
 */
void merge(vector<int>& data, int left_1, int right_1, int left_2,
           int right_2)

You can then use Doxygen to generate documents