C++ 文档 Doxygen/Breathe 语法#

备注

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

警告

不是所有的 Doxygen 语法（如折叠等）都能够在 MegEngine 文档中被使用， 我们仅使用它来提取信息，而用 Breathe 来构建文档，参考 从源码到文档的流程 小节。

一份参考模板#

下面这个例子修改自 Breathe 官方文档的 Nutshell 示例：

/**
 * @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 拓展样式，使用时通过 ReStructuredtext 语法来解析。 当默认的样式不满足需求时，可以使用 Sphinx reStructuredText 语法入门 中展示的各种语法作为拓展。 但需要注意的是，由于使用了前导星号，为了能够被正常解析，需要使用 embed:rst:leading-asterisk 标记：

/*!
* Inserting additional reStructuredText information.
*
* \verbatim embed:rst:leading-asterisk
*     .. note::
*
*        This is a example.
* \endverbatim
*/

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

.. note::

   This is a example.

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

从源码到文档的流程#

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

flowchart LR HF[C++ Head Files] --> |Doxygen| XML[XML Files] XML --> |Breathe Directive| Sphinx[Sphinx RST Doc]

由于 MegEngine 文档与 MegEngine 源码不在同一处维护， 因此开发人员通常会规律性地使用 Doxygen 从 MegEngine 的 C++ 源码中生成最新的 XML 文件 （位于 doxyxml 目录中）。 平时撰写文档只需要使用 Breathe 将 XML 中的信息转换成 Sphinx 的 RST 文档， 体验上与从 MegEngine 的 Python Package 生成 API 文档类似。

以 Tensor 为例子，添加 Python 接口和 C++ 接口（生成文档）的 Sphinx 语法对比如下：

.. autoclass:: megengine.Tensor

.. doxygenclass:: lite::Tensor

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

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

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

详细的 Sphinx 和 Breathe 文档语法对比