20230419-C++文档doxygen/breathe语法

字数统计: 4.3k   |   阅读时长≈ 17 分钟

本手册用来给megengine 开发者提供常见的c++接口文档的语法模板作为参考，帮助其高效地撰写和修改复合megengine 工程规范的面向用户的c++接口文档

不是所有的doxygen 语法都能在megengine 文档中被使用，我们仅使用它来提取信息，而用breathe 来构建文档，

一份参考模块

下面这个例子改自Breathe 官方文档的nutshell 示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
/**
 * @file nutshell.h
 *
 * @brief This is a nutshell example.
 */

/*!
 *  With a little bit of a elaboration, should you feel it necessary.
 */
class Nutshell
{
public:

   //! Our tool set
   /*! The various tools we can opt to use to crack this particular nut */
   enum Tool
   {
      kHammer = 0,          //!< What? It does the job
      kNutCrackers,         //!< Boring
      kNinjaThrowingStars   //!< Stealthy
   };

   //! Nutshell constructor
   Nutshell();

   //! Nutshell destructor
   ~Nutshell();

   /*! Crack that shell with specified tool
    *
    * @param tool - the tool with which to crack the nut
    */
   void crack( Tool tool );

   /*!
    * @return Whether or not the nut is cracked
    */
   bool isCracked();

private:

   //! Our cracked state
   bool m_isCracked;

};

注意事项

多行注释中带有前导星号 leading-asterisk * 而非单纯的空行

使用@param 代替\param 写法，避免遇到后者形式在其他解析工具中被转义的情况

MegEngine 文档只要是公开接口、成员，不论是否有相应备注，都会生成对应的api 文档

使用breathe 语法

breathe 文档中提供了一些简单的语法模板，可以在c++接口文档中添加数学公式、列表、表格等样式，在简单情况下可以使用

参考breathe features 页面中给出的各种样例

对于比较复杂的文档内容编辑和排版需求，推荐使用下一小节提到的ReST 语法，即 MegEngine 文档中最常使用的语法

使用ReST 语法和组件

MegEngine文档中使用了比较多的sphinx 拓展样式，使用时通过resTructuretext 语法来解析，当默认的样式不满足需求时，可以使用sphinx restructuretext 语法入门中展示的各种语法作为拓展，但需要注意的是，由于使用了前导星号，为了能够被正常解析，需要使用 embed:rst:leading-asterisk 标记

1
2
3
4
5
6
7
8
9
/*!
* Inserting additional reStructuredText information.
*
* \verbatim embed:rst:leading-asterisk
*     .. note::
*
*        This is a example.
* \endverbatim
*/

它等同于在C++ 接口文档中插入了如下ReST语法

1
2
3
.. note::

   This is a example.

会得到对应的note 样式块内容，同理，你还可以使用这种方法来插入 数学公式和图片等等内容

从源码到文档的流程

MegEngine 的C++源码经历了如下流程变成megengine 文档中的api 参考页面

C++ head files doxygen xml files breathe directive sphinx rst doc

由于MegEngine 文档与MegEngine 源码不再同一处维护，因此开发人员通常会规律性地使用doxygen 从MegEngine 的c++ 源码中生成最新的xml 文件，位于doxyxml 目录中，平时撰写文档只需要使用breathe 将xml 中的信息转换成sphinx 的rst 文档，体验上与从 MegEngine 的python package 生成api 文档类似

以tensor 为例子，添加python 接口和c++接口 生成文档的sphinx 语法对比如下

1
2
3
.. autoclass:: megengine.Tensor

.. doxygenclass:: lite::Tensor

使用自动生成的文档的好处之一是，方便在文档其他的任何地方进行引用

1
比如此处直接引用 :class:`megengine.Tensor` 与 :cpp:class:`lite::Tensor` 的 API 文档。

详细的sphinx 和breathe 文档语法对比

Breathe 文档

breathe 在sphinx 和doxygen 文档系统之间提供了一座桥梁

这是一个简单的方法，将doxygen 信息包含在由sphinx 生成的一组文档中，目的是为那些喜欢使用sphinx 但用python 以外的语言工作的人制作一个类似autodoc的支持，该系统依赖于doxygen的xml输出

警告

这个文档的构建不是来自于breathe的一个特定的标记版本，它反映了breathe的工作进展状态，请参阅github 仓库 https://github.com/michaeljones/breathe ，以获得更多的官方信息

概述

简单的设置，一个doxygen 配置值，一个sphinx 配置值和一个指令，你就可以上路了

高级和低级指令，引用整个项目，只是一个类或只是一个函数的不同指令

支持多个doxygen 项目，将其设置为知道不同的项目，并在每个指令中通过名称或路径引用它们

允许在doxygen 标记中嵌入reStructureText 一些额外的doxygen 别名允许你在评论中添加 rst endrst 块，并将内容解释为reStructureText

对sphinx 域的基本支持，用标准的sphinx 域引用链接到breathe输出中的函数

设置与使用

快速入门

Directives Config Variables
与doxygen 和autodoc的差异

running on Read the docs

特性

Supported markups

latex math
domains

custom css
groups
lists
tables

template

贡献

contribute to breathe

how it works
credits

示例 测试页面

test pages

下载

breathe 可从以下网站获得

pypi the python package index
github

简而言之

你写的代码看起来有点像这样：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
/**
    \file nutshell.h
    An overly extended example of how to use breathe
*/

/*!
    With a little bit of a elaboration, should you feel it necessary.
*/
class Nutshell
{
public:

    //! Our tool set
    /*! The various tools we can opt to use to crack this particular nut */
    enum Tool
    {
        kHammer = 0,          //!< What? It does the job
        kNutCrackers,         //!< Boring
        kNinjaThrowingStars   //!< Stealthy
    };

    //! Nutshell constructor
    Nutshell();

    //! Nutshell destructor
    ~Nutshell();

    /*! Crack that shell with specified tool

      \param tool - the tool with which to crack the nut
    */
    void crack( Tool tool );

    /*!
      \return Whether or not the nut is cracked
    */
    bool isCracked();

private:

    //! Our cracked state
    bool m_isCracked;

};

然后你运行这个

1
doxygen

有一个设置是这样说的

1
GENERATE_XML = YES

然后在你的 Sphinx 文档中，你可以添加这样的内容

1
2
3
.. doxygenclass:: Nutshell
   :project: nutshell
   :members:

通过像这样的 conf.py 设定

1
2
3
breathe_projects = {
    "nutshell":"../../examples/specific/nutshell/xml/",
    }

并在 conf.py 中把 Breathe 注册为一个插件，像这样

1
extensions = [ "breathe" ]

你会得到类似这样的东西：

  • class Nutshell

    With a little bit of a elaboration, should you feel it necessary.Public Typesenum Tool Our tool set.The various tools we can opt to use to crack this particular nutValues:enumerator kHammer What? It does the job.enumerator kNutCrackers Boring.enumerator kNinjaThrowingStars Stealthy.Public Functions**Nutshell() Nutshell constructor.~Nutshell() Nutshell destructor.void crack(Tool tool) Crack that shell with specified tool参数tool – the tool with which to crack the nutbool isCracked() 返回Whether or not the nut is cracked

================

快速入门

对于这个快速入门，我们假设有以下先决条件

在某处下载并提取了breathe
已经安装了doxygen 并且为要记录的项目生成了doxygen xml 格式 将 GENERATE_XML 标签设为 YES

我们假设有以下的路径

文档根路径
breathe 路径

doxygen xml 输出路径

文档路径应该包含一个文件夹source 其中包含conf.py 文件，doxygen xml 输出文件夹应该包含index.xml 由doxygen 生成的输出文件

要整合breathe 功能，需要采取以下步骤

在你的 conf.py 中添加breathe 路径，方法是添加以下一行

sys.path.append( “/home/me/docproj/ext/breathe/“ )

添加 breathe 作为插件，这一行可以这样写

extensions = [‘sphinx.ext.pngmath’, ‘sphinx.ext.todo’, ‘breathe’ ]

告诉 breathe 关于项目的信息

breathe_projects = { “myproject”: “/home/me/docproj/doxyxml/“ }

指定默认的项目

breathe_default_project = “myproject”

一旦完成这些工作，你可以使用以下命令

1
2
3
4
5
6
.. doxygenindex::
.. doxygenfunction::
.. doxygenstruct::
.. doxygenenum::
.. doxygentypedef::
.. doxygenclass::

以包括不同结构的文档，对于这些命令中的每一条，都可以指定以下指令

project 指定哪个项目，如breathe_projects 配置值中定义的，应该用于该指令，这取代了默认值

path
直接指定到有doxygen 输出的文件夹的路径，这覆盖了project 和default project

指令和配置变量

指令和配置变量

directives 指令

doxygenclass
doxygendefine
doxygennum
doxygennumvalue
doxygenfile
autodoxygenfile
doxygenfunction
doxygengroup
doxygenindex
autodoxygenindex
doxygennamespace
doxygenstruct
doxygeninterface
doxygentypedef
doxygenunion
doxygenvariable
doxygenpage

config values 配置值

指令

可用的指令如下所示，在每种情况下，project path no-link 和outline 选项具有以下含义

project 指定配置值中定义的项目，应该用于此指令，这将覆盖默认项目 如果有，已指定 breathe_projects

指令不使用此功能，改为用于指定配置值中的条目来使用 autodoxygenindexsourcebreathe_projects_source

path 直接指定具有doxygen 输出的文件夹的路径，这覆盖项目和默认项目 如果已指定

指令不使用此功能，改为用于指定要成为的源文件的根路径 autodoxygenindexsource-path

no-link 指示 breathe 不要尝试为此特定指令生成的内容

这使您可以将主要参考列表放在具有以下位置的某个位置目标，但随后能够将重复指令潜入其他指令，

部分文档来说明将特定要点，但没有sphinx 对其他参考资料应该链接到什么感到困惑

outline 导致breathe 仅输出原始代码定义，而无需任何其他描述信息

如果指令上既没有提供项目也没有提供路径，那么breathe 将 breathe_default_project 配置值为设置

此指令为单个类生成适当的输出，它采用标准项目、路径、大纲和无链接选项，此外还有 members protected-members private-members undoc-members membergroups 和members-only 选项

1
2
3
4
5
6
7
8
9
10
11
.. doxygenclass:: <class name>
   :project: ...
   :path: ...
   :members: [...]
   :protected-members:
   :private-members:
   :undoc-members:
   :membergroups: ...
   :members-only:
   :outline:
   :no-link:

重看 doxygenclass 文档以获取更多详细信息 并看到它的实际效果

doxygendefine

此指令为单个预处理器生成适当的输出定义，它的行为与doxygenstruct 指令相同

1
2
3
4
5
.. doxygendefine:: <define name>
   :project: ...
   :path: ...
   :outline:
   :no-link:

重看示例以查看其实际效果

doxygenenum

此指令为单个枚举生成适当的输出，它的行为与doxygenstruct 指令相同

1
2
3
4
5
.. doxygenenum:: <enum name>
   :project: ...
   :path: ...
   :outline:
   :no-link:

doxygenenumvalue
此指令为单个枚举值生成适当的输出

doxygenfile
此指令为源的内容生成适当的输出文件

autodoxygenfile
此指令是上述doxygenfile 指令的此版本，它像其他自动指令一样为您处理doxygen xml 生成auto

查看示例以查看其实际效果

doxygenfunction

此指令为单个函数生成适当的输出，这个函数名称在项目中是唯一的

doxygengroup
此指令为doxygen 的内容生成适当的输出群，可以使用特定的doxygen 标记声明doxygen 组来源注释如 doxygen 分组文档中所述

它采用标准的project path outline 和no-link 选项和content-only members protected-member private-members undoc-members 选项

查看 doxygengroup 文档以获取更多详细信息，并看到它的实际效果

doxygenindex

该指令处理并生成由 doxygen xml 输出，它读取文件并处理所有内容 由它引用 index.xml

autodoxygenindex

此指令执行与指令类似的角色，除了它为您处理doxygen xml 生成，它使用配置字典来判断哪个代码源文件应具有为其生成doxygen xml 该指令选项将指令与字典中的特定项目相关联，中条目引用的所有文件将包含在输出中，此外，任何中指定的选项将添加到生成的doxygen 配置文件和中指定的任何自定义别名都将添加到 doxygen 别名中

doxygennamespace

此指令为命名空间的内容生成相应的输出

It takes the standard project, path, outline and no-link options and additionally the content-only, members, protected-members, private-members and undoc-members options.

要引用嵌套命名空间，必须提供完整的命名空间路径，例如，对于命名空间内的命名空间， foo::bar bar

查看doxygennamespace 文档了解更多信息，细节并查看它的实际效果

doxygenstruct
此指令为单个结构生成适当的输出，结构体名称在项目中必须是唯一的

It takes the standard project, path, outline and no-link options and additionally the members, protected-members, private-members, membergroups, members-only and undoc-members options.

查看示例以查看其实际效果

doxygeninterface

此指令为单个接口 专门使用 类，它的行为与doxygenclass 指令相同

doxygentypedef

此指令为单个typedef 生成适当的输出，它的行为与doxygenstruct 指令相同

doxygenunion

此指令为单个联合生成适当的输出，它的行为与doxygenstruct 指令相同

doxygenvariable

此指令为doxygen 的内容生成适当的输出页，为每个使用xrefitem 命令的每个键创建一个doxygen页面用于源注释中的标记，有关详细信息，请查看doxygen外部参照文档

它采用标准 project 和 path 选项，以及 content-only选项，

查看doxygenpage 文档以获取更多详细信息，并看到它的实际效果

config values
breathe_projects

这应该是一个字典，其中键是项目名称，值是包含该项目的doxygen 输出的文件夹的路径

breathe_default_project

这应该与字典中的一个键匹配，并且指示在未指定项目时应该使用哪个项目指令

breathe_domain_by_extension

允许您根据特定文件的域指定域外框

breathe_domain_by_file_pattern
允许您通过通配符语法为特定文件指定域，这之后被检查，因此将覆盖必要时

如果您希望将所有头文件都视为在cpp 域中，您可以使用以下示例 以上，但是，如果您有一个文件应被视为在c 域中，那么您可以如上所述进行覆盖，

breathe_projects_source

其中键是项目名称，值是元组的字典的目录和这些目录的源代码文件名列表，您希望使用doxygen 自动处理的项目，如果您在以下位置有一些文件

1
2
/some/long/path/to/myproject/file.c
/some/long/path/to/myproject/subfolder/otherfile.c

然后，您可以设置

1
2
3
4
breathe_projects_source = {
   "myprojectsource" :
       ( "/some/long/path/to/myproject", [ "file.c", "subfolder/otherfile.c" ] )
   }

然后，您的 autodoxygenfile 使用情况可能如下所示 

1
2
.. autodoxygenfile:: file.c
   :project: myprojectsource

元组中的目录条目可以是空字符串，如果，列表是完整路径

breathe_build_directory

为了处理breathe，必须运行以创建要处理xml 文件，此配置值指定根应在其中创建这些文件的目录，默认情况下，这设置为输出文件夹的父目录，即正常构建目录，如果您有自定义，则可以使用此设置进行更改，

breathe 将采用最终值并附加到路径以最大程度地减少冲突

breathe_default_members

提供应用于所有指令的指令标志 采取 和选项，默认情况下，此选项设置为空列表，这意味着没有成员显示，如果您想始终显示公众和公众，无文档成员，那么您可以像这样设置它

breathe_default_members = (‘members’, ‘undoc-members’)

breathe_implementation_filename_extensions
提供被视为实现文件，当指令查找未命名的函数名称时，将忽略这些文件，这是为了避免问题标头的doxygenxml 输出中出现相同的函数名称 文件和实现文件，因为声明在一个和定义在另一个，doxygen 将文档从定义到声明的xml 因此我们不会错过任何文档 来自实现文件的信息，此值的默认值 变量为 doxygenfunction

breathe_implementation_filename_extensions = [‘.c’, ‘.cc’, ‘.cpp’]

breathe_doxygen_config_options

一个字典，其中键和值是配置的名称和值，要放置在由 autodoxygenindex 生成的doxygen 配置文件中的选项

breathe_doxygen_config_options = {‘EXCLUDE_SYMBOLS’: ‘abc123’}

将放置在配置文件中，默认值为空字典，exclude_symbols=abc123

breathe_doxygen_aliases

其中键和值是别名的名称和值的字典，放置在由 autodoxygenindex 生成的doxygen 配置文件中

breathe_doxygen_aliases = {‘rstref{1}’: r’\verbatim embed:rst:inline :ref:\1 \endverbatim’}

将放置该行

ALIASES += rstref{1}=”\verbatim embed:rst:inline :ref:\1 \endverbatim”

在配置文件中，默认值为空字典，请注意使用原始字符串以确保反斜杠解释为文字字符，此示例别名允许使用 rstref

breathe_show_define_initializer

一个布尔标志，可以设置为在输出中显示定义的初始值设定项 true

例如，如果将定义 MAX_LENGTH 100 设置为值为100 True 不带则为false

breathe_show_enumvalue_initializer

一个布尔标志，可以设置为在输出中显示枚举值的初始值设定项，True

例如，如果将枚举值设置为 TWO=2 为true 否则为false

breathe_show_include

一个布尔标志，可以设置为隐藏每个标头定义实体 结构 函数，宏 等 false

例如，当设置为 True struct foo 将呈现

但当设置为false 时，将呈现

breathe_use_project_refids

真或假设置，用于控制呼吸氧气是否产生的反射元素是否包含项目名称，旧版 行为是所有refid 都以项目名称为前缀，这导致尝试在多个项目之间链接文档时出现问题，因为项目无法看到彼此的文档元素，新的默认行为是不在refid 前面加上项目名称

breathe_use_project_refids = True

如果需要，将恢复旧行为

breathe_order_parameters_first

True或false 设置，用于控制是否从doxygen 生成的参数部分 文档应紧跟在 简短和详细的描述之后，或在最后，在返回，备注和警告部分之后，默认值和旧行为也是false

breathe_separate_member_pages

True 或false 设置，用于控制doxygen 生成的输入xml 是否具有 doxygen separate_member_pages 选项设置为是或否，doxygen 选项末尾到no 生成允许breathe 解析所有引用的xml 设置时是的，元素 refid 得到一个额外的元素，呼吸试图摆脱它，当此设置为True 时

打赏
  • 版权声明： 本博客所有文章除特别声明外，著作权归作者所有。转载请注明出处！

扫一扫，分享到微信

微信分享二维码
  • Copyrights © 2015-2024 TeX_baitu
  • 访问人数: | 浏览次数:

请我喝杯咖啡吧~