# doxygenTest

**Repository Path**: longlongint/doxygen-test

## Basic Information

- **Project Name**: doxygenTest
- **Description**: No description available
- **Primary Language**: C++
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2020-10-10
- **Last Updated**: 2023-03-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README


# 一、简介 {#mainpage}
[TOC] doxygen 笔记 
> doxygen是解析源代码并生成文档主程序。有关更详细的用法信息，请参阅官网[https://www.doxygen.nl/manual/starting.html](https://www.doxygen.nl/manual/starting.html)，它有图形界面用来编辑配置信息，在MAC OS 中可以直接双击图标运行

> ![工具相关信息关系图](./picture/infoflow.png)
- 使用前：检查doxygen是否支持您的编程语言
    - 默认支持以下语言：C，C ++，C＃，Objective-C，IDL，Java，VHDL，PHP，Python，Fortran和D。可以配置某些文件类型扩展名以使用某些解析器。另外，通过使用预处理程序，可以支持完全不同的语言：有关详细信息，请参见“帮助程序”页面。
    - 为了简化配置文件的创建，doxygen可以为您创建模板配置文件。为此，请使用-g选项从命令行调用doxygen

            doxygen -g <config-file>

        - 如果您使用-（即减号）作为文件名，则doxygen将尝试从标准输入（stdin）读取配置文件，这对于脚本编写很有用。
    - 配置文件的格式类似于（简单）Makefile的格式。它由多种形式的标签组成：

            TAGNAME = VALUE or
            TAGNAME = VALUE1 VALUE2 ...

        - 您可能可以将生成的模板配置文件中大多数标记的值保留为其默认值。有关配置文件的更多详细信息，请参见“配置”部分。
        - 如果您不希望使用文本编辑器编辑配置文件，则应查看doxywizard，它是一个GUI前端，可以创建，读取和写入doxygen配置文件，并允许通过配置选项来设置配置选项。
        - 对于由几个C/C++源文件和头文件组成的小型项目，可以将INPUT标记保留为空，并且doxygen将在当前目录中搜索源。
    
## 1.安装
- 参见 [https://www.doxygen.nl/download.html](https://www.doxygen.nl/download.html)

        sudo apt-get install flex
        sudo apt-get install bison
        git clone https://github.com/doxygen/doxygen.git
        cd doxygen
        mkdir build
        cd build
        cmake -G "Unix Makefiles" ..
        make
        sudo make install

## 2.使用
- 使用下面的命令生成文档：
    - doxygen \<config-file\>
- 根据你的配置文件可以生成 html、rtf、latex、xml、man目录及对应文件
- 使用 OUTPUT_DIRECTORY 标签改变输出目录， HTML_OUTPUT, RTF_OUTPUT, LATEX_OUTPUT, XML_OUTPUT, MAN_OUTPUT, and DOCBOOK_OUTPUT用来设置相关文件的特定目录名
- MAN 包的输出
    - 参考全局变量 ```MANPATH```,手册页格式可能存在一些限制，如类图和交叉引用公式将丢失
- [DocBook](https://www.doxygen.nl/manual/starting.html)
- 文档化你的代码
    - 如果 ```EXTRACT_ALL``` 选项设置为NO,则doxygen只会格式化文档化的资源，那么应该怎么文档化呢？对于成员、类、命名空间，有两点基础的建议：
        - 1.在声明成员、类、命名空间前空搞一块特殊的"文档块"。对文件、类和命名空间，"文档块"可以直接放置在成员后面
        - 放置一个特殊的["文档块"](https://www.doxygen.nl/manual/docblocks.html#structuralcommands)在其他位置(可是另一个文件),然后在文档中放置一个结构命令，这个结构化命令将文档编制块链接到可以记录的特定实体（例如，成员，类，名称空间或文件）。
        > 文件当然只能使用第二中方法。文件的成员(函数、变量、、、)不需要一个显示的结构化命令，直接放置"文档块"到声明前或后就行了。
- 输出前文档要先进行解析：
    - Markdown 格式会被替换称相应的HTML或特使命令
    - [特殊命令](https://www.doxygen.nl/manual/commands.html)被执行
    - 如果某行以空格加星号开头，则后面的所有星号和空格都将被删除
    - 所有空白行都被视为段落或分隔符
    - 所有的类名(单词)都会被创建连接，除非前面加了%号
    - 在文本中找到某些特定的[模式](https://www.doxygen.nl/manual/autolink.html)时,将创建指向成员的链接
    - 文档中的[HTML标记](https://www.doxygen.nl/manual/htmlcmds.html)将被转换为等效的输出

---


# 二、文档化你的代码
- 本章主要包括
    - 1.怎么在代码中添加(doxygen能识别的)注释
    - 2.怎么构造注释块让输出更好看
## 特殊注释块
- 定义：是带有其他标记的C/C++注释块
- 类C语言注释块(C/C++/C#/Objective-C/PHP/Java)
    - 代码中的每个实体都有两种或三种描述类型，简要说明和详细说明。对于方法和函数，还有主体描述(方法或函数中找到的所有注释块串联组成)
    - 有几种方法可将注释块标记为详细描述
        - 1、Javadoc 风格

                /**
                * 
                */

        - 2、Qt风格

                /*!
                * 注释块1
                */

            or

                /*!
                注释块1
                */

        - 3、使用至少两个C++注释行的块，每行附加斜杠或感叹号

                ///
                /// 注释1

            or

                //!
                //! 注释2

        - 4、有些人希望他们的注释更明显,喜欢用这种带横幅的

                /********************************************//**
                *  ... 注意是已两个斜杠结束普通注释块并且两个星号开始
                ***********************************************/

            or

                /////////////////////////////////////////////////
                /// ... text ...
                /////////////////////////////////////////////////

            or

                /************************************************
                *  ... text
                ***********************************************/

        - 例：
        ![](./picture/comment.png)
- 关于简介，有几个要注意的地方
    - 使用[\brief](https://www.doxygen.nl/manual/commands.html#cmdbrief)
    - 设置[ JAVADOC_AUTOBRIEF](https://www.doxygen.nl/manual/config.html#cfg_javadoc_autobrief)为YES
        - 注意最后一个例子中 的空白行，这是将简短描述与包含详细描述的块分开所必需的
        - 如图：
        ![简介注释](./picture/brifeComment.png)
        - doxygen是很灵活的，像下面这种注释也是允许的

                //! Brief description, which is
                //! really a detailed description since it spans multiple lines.
                /*! Another detailed description!
                */

        - 不同与其他的文档系统，doxygen 允许你将注释放在成员定义之前，这样你就能将注释放在源文件中，而使头文件保持紧凑，作为一种折中，可以在声明前放一个简短说明，成员定义之前放置详细说明。
- 把注释放在(结构联合枚举的)成员之后，需要一个额外的 ```<```

        int var; /*!< 详细描述，注意 < 表示成员在注释之前 */
        int var; /**< 该块可用于在成员之后放置Qt样式的详细文档块。其他相同的方法是： */
        int var; //!< Detailed description after the member
                //!< 
        int var; ///< Detailed description after the member
                ///< 
        int var; //!< 大多数情况下，一个成员只想简短描述一下。可以这样做：
        int var; ///< Brief description after the member

    - 对于函数，可以用```@param```命令记录参数，用\[in\]、\[out\]记录方向
    ![](./picture/aTestClass.png)
    - ```注：```这些注释只能记录成员和参数，文档、类本身的结构命令将在下节介绍
    - Qt风格注释：

        ![](./picture/QtS.png)
        - 简要描述包含在了类、命名空间或文件的成员概述中了(BRIEF_MEMBER_DESC=NO隐藏)，默认简要描述为详细描述的第一句话(REPEAT_BRIEF=NO更改)
    - 设置 ```JAVADOC_AUTOBRIEF``` 为 YES，则注释的第一句话被视为简要说明，以点结束(不想结束则跟反斜杠加空格)

            /** Brief description (e.g.\ using only a few words). Details follow. */

    - Java风格

        ![](./picture/JaS.png)
- 注释放在其他地方
    - 注释放在声明定义的前面很是很舒适的，但有些情况需要将注释与定义分离，你可以将注释放在函数体外或C样式注释体外的任何地方。
    - 代价是需要在注释中加入结构性命令，所以你应该尽量避免这样做
    - ```结构命令以斜杠或@开头+命令名+一个或多个参数```

            /*! \class Test
                \brief A test class.

                Test是一个类.
            */

    - 其他结构命令还有：```@struct @union @enum @fn @var @def @typedef @file @namespace @package @interface```
    - [更多特殊命令点这里](https://www.doxygen.nl/manual/commands.html)
    - __```要注释C++类的成员，必须先注释类本身，先注释文档本身(/*! \file */ 或 /** @file */ )```__
    - c风格头文件注释范例

        ![](./picture/CheadS.png)

    - doxygen将在文件列表中隐藏 .dox .txt .doc文件
    - 如果有doxygen无法解析但想原样显示的文件，可用```\verbinclude```, 这样写

            /*! \file myscript.sh
            *  Look at this nice script:
            *  \verbinclude myscript.sh
            */

        - 需确保脚本在```INPUT```中明确列出了，或者```FILE_PATTERNS```包含sh扩展名且```EXAMPLE_PATH```设置的路径中找到该脚本
- Python和其他语言的注释请自行查阅官网
- 注释块剖析
    - 上面章节中讲解了怎么使用注释、简短描述和详细描述的区别，本节关注注释块本身的内容。Doxygen支持各种格式的注释格式。最简单的形式是使用纯文本。这将按原样显示在输出中，是简短说明的理想选择。
    - doxygen还支持 [markdown格式](https://www.doxygen.nl/manual/markdown.html)
    - doxygen还支持[HTML标记语言的子集](https://www.doxygen.nl/manual/htmlcmds.html)


---
# Markdown支持
- 在doxygen 1.8.0版本中引入，具有以下设计目标
- 行内的代码使用``` ` ```包围
- 链接网址 [baidu]

[baidu]: http://baidu.com/     "Baidu"
[CheadS]: ./picture/CheadS.png "CHeadStyle"

- 链接类直接输入类名也可 @ref Javadoc_Test
- 链接函数  @ref main
- 链接图片 \!\[CheadS\]\(@ref ./picture/CheadS.png\)

        ![img Test]
        [img Test]: @ref ./picture/CheadS.png "Caption text"

## markdown 扩展
- 使用 ```[TOC]``` 标记或 ```\tableofcontents``` 标记可以生成目录
- 支持表格,如：

        | Right | Center | Left  |
        | ----: | :----: | :---- |
        | 10    | 10     | 10    |
        | ^     | 1000   | 1000  |

        | Right | Center | Left  |
        | ----: | :----: | :---- |
        | 10    | 10     | 10    |
        | 1000  |||
- 代码可以用三个以上的```~```包围,或三个反引号``` ` ```(不需要缩进)，如
    <p>   ~~~~~~~~~~~~~~~~~~~~~{.py}
    <p>   a one-line code block
    <p>   ~~~~~~~~~~~~~~~~~~~~~

    ```
    also a fenced code block
    ```
- 标头ID属性:
```{.css}
Header 1                {#labelid}
========

## Header 2 ##          {#labelid2}
链接：
[Link text](#labelid)
[Link text](@ref labelid)
```
## doxygen的特殊markdown语法
- 包含markdown文件作为一个页面
    - 如果你的markdown文件的扩展名不是.md或者.markdown，请使用 EXTENSION_MAPPING 标签
    - 如果文件不以一级标题开头，则页面名是文件名，否则页面名是一级```标题名```或```标题的标签```
    - 如果标签是``` {#mainpage}```或者```{#index}```，则页面将被放在主页
    - 可以用@ref+文件名链接到另一个文件
- HTML块的处理
    - Markdown在处理块级HTML的方式上非常严格：  像 \<div\>, \<table\>, \<pre\>, \<p\>必须用空行将其与周围的内容分开，并且该块的开始和结束标签不应使用制表符或空格缩进

- 代码块缩进
    - 使用单个制表符或4个空格启动代码块

- 强调线和删除线
- 代码跨度限制
    - 单引号会取消对用反引号引起来的代码段的特殊处理

---
# 列表
doxygen提供了很多创建元素列表的方法

- 使用破折号
    - 可以在开头放置多个列对齐的减号、加号、星号、数字
    - @ref listTestFunc
    - 可以通过在要结束的列表相同缩进级别的空行放一个点来结束列表
    - 如果你愿意，也能用\<ul\>\<li\>这些HTML标签

---
# 图形和图表
doxygen具有内置的为C++类生成继承图的功能(666~)
<br>如果你有[dot](http://www.graphviz.org/)工具，可以将 ```HAVE_DOT``` 标签设置为 YES
- doxygen可以用dot工具生成下面这些图形
    - 表示一个类的层次结构的图(有些浏览器可能不支持太大的图)
    - 为每个类生成一个继承图，显示直接和间接继承关系
    - 为每个包含至少一个其他文件的文档文件生成一个包含关系依赖图
    - 还会生成一个反向包含相关性图，显示一个（头）文件，其他文件也包含它
    - 为每个记录的类和结构绘制一个图形，该图形显示：
        - 与基类的继承关系。
        - 与其他结构和类的使用关系（例如，类A具有类型B的成员变量m_a，然后A带有B的箭头，其中m_a作为标签）
    - 如果 ```CALL_GRAPH```设置为YES, 则会为每个函数绘制图形调用图
        - 参见 [\callgraph](https://www.doxygen.nl/manual/commands.html#cmdcallgraph)、[\hidecallgraph](https://www.doxygen.nl/manual/commands.html#cmdhidecallgraph)
    - 如果 ```CALLER_GRAPH```设置为YES, 则为每个函数绘制一个图形的调用者图，
        - 参见 [\callergraph](https://www.doxygen.nl/manual/commands.html#cmdcallergraph)、 [\hidecallergraph](https://www.doxygen.nl/manual/commands.html#cmdhidecallergraph)
- 使用一个[布局文件](https://www.doxygen.nl/manual/customize.html)可以决定实际显示哪些图形
- ```DOT_GRAPH_MAX_NODES```、 ```MAX_DOT_GRAPH_DEPTH```两个标签可以用来限制各种图的大小
- HTML和RTF中的类图中的元素具有以下含义：
    - 黄框表示类
    - 白框表示该类的文档
    - 灰表未记录
    - 深蓝表公共继承
    - 深绿虚线箭头表示受保护的继承
    - 虚线的深绿箭头表示私有继承

---
# graphviz
- [windows版本](https://www.doxygen.nl/files/doxygen-1.8.20-setup.exe)和[linux版本](https://www2.graphviz.org/Packages/stable/portable_source/graphviz-2.42.1.tar.gz)都能在[官网](https://graphviz.org/doc/info/output.html)找到
    - [windows版本使用前需要先激活](),管理员方式运行cmd,输入命令 ```dot -c```
    - linux版本我在windows子系统下使用源码编译成功但是仍然不能用,在ubuntu系统环境下直接使用命令apt-get install graphviz安装后可以直接使用


---
# UML
- UML_LOOK 标签设置为yes可以为类生成类似UML风格的图
- 暂未找到doxygen支持UML文件的方法
---
# PDF
- [pdflatex](https://www.latex-project.org/get/)

## 注意事项
- 1、路径不要包含中文，否则生成的 chm 只有目录，没有实际内容