QDox，编写文档

QDox 允许您从 .cpp 文件生成文档（ReStrcturedText、sphinx rst） （以及将来的晚些时候 - 可能来自 .nut quirrel 模块）。

用 Python 3.10 编写，没有外部依赖项，应该可以在 Python 3.9 或更高版本中使用。 受 LuaDox 的启发，但写得更脏，可能需要重构。 无法使用 LuaDox，主要是因为 cpp 和 lua 的注释样式不同，而是因为 Quirrel 是更复杂的语言，我想尝试从 cpp 文件中获得更多

尚未完成但将来可以完成的内容：

• 超出范围定义和更高以后的绑定。可以生成未引用的对象。

• 多范围路径定义``@class foo/bar/Baz`` – 在模块 foo 和表 bar 中添加类 Baz

• 支持 @example @usage @image @icon 和其他方便的东西

• 多行参数和返回定义

• 从解析的表示中生成存根（目标之一）

但它可能需要再次大幅重写 parser。所以也许以后。

如何注释 cpp 代码的简要示例：

part of sqWebBrowser.cpp

void bind_webbrowser(SqModules* sq_modules_mgr)
{
  Sqrat::Table tbl(sq_modules_mgr->getVM());
  /**@module browser

打开嵌入式 Web 浏览器。需要本机 cef 二进制文件及其集成。

  */
  tbl
    .Func("can_use_embeded_browser", can_use_embedded_browser)
    ///@return b : Returns can browser be opened
    .Func("browser_go_back", go_back)
    .Func("browser_reload_page", reload)
    ///Will reload page
    .Func("browser_add_window_method", add_window_method)
    ///@param method c : add function
  ;

  using namespace webbrowser;

  CONST(BROWSER_EVENT_INITIALIZED);
  CONST(BROWSER_EVENT_DOCUMENT_READY);

  sq_modules_mgr->addNativeModule("browser", tbl);
}

基础知识

所有 QDox 注释都应该以三个斜杠 /// 或 doxygen 样式的多行注释 /** */ 开头。

一切都以 @module 或 @page 开头 你应该把 ///@module <your module name> 或 ///@page <your page name> 放在文件的某个地方， 因为没有 module ，所有其他东西都无法添加

您需要了解几个指令：

集合或容器中可以包含一些其他成员：

• @module 或 @page 可以有 tables、classes、functions、consts、values、enums。通常它会导出一个表。

• @table 可以包含函数、类、枚举、表、const 和值

• @class 可以有函数、ctor、运算符、Var、Prop、Const

• @enum 只能有 const 和 values

‘Leaf’ 对象（不能有成员）：

• @function - 只能在 TABLES 或 MODULE 中

• @ctor - 只能在类中

• @operator - 只能在类中

• @property - 只能在类中

• @var - 只能在类中

• @value - 可以是在 module， table， class， enum中

• @const - 可以是在 module， table， class， enum中

‘Doc’ 对象:

• multiline - @code, @expand, @tip, @seealso, @warning, @tip, @alert 或 @danger, @note. 当 <tag_name>@ 出现 （如 code@, tip@,等） 或注释结束时，这些对象会关闭它们的作用域。 这些对象可以在任何范围内，因为它们只是添加了创建 rst 的简单方法（见下文）

每个对象 - 容器或叶类型 - 都可以使用 module 的 scope 来定义。

@class myModule/MyClass 将设置 MyClass 在 myModule 中。

函数、表和类可以定义为一个模块：

@class DataBlock = DataBlock 将描述导出类 DataBlock 的模块。

在函数作用域（以及 operator 和 ctor）中，您可以使用以下指令：

• @paramsnum - 参数数量的 integer（在 cpp 中称为 paramscheck）。 如果为负数 - 表示可以使用至少该数量的参数调用函数，但也可以使用更多参数调用该函数。

• @kwarged - 表示函数参数应通过 table 提供。喜欢： function foo({argument=1, arg2=2})

• @typemask - string 替换为 typemask 的 String。看`documentation <https://quirrel.io/doc/reference/api/object_creation_and_handling.html#c.sq_setparamscheck>`_

• @vargved - 表示函数可以具有变量参数 count

• @param - 应该是 @param <name> <type> : description, 例如 @param title t : Title of messagebox

• @return - 应该是 @return typemask : any description 或 @return typemask

Note

除了 doc-objects， @param 和 @return 之外，所有指令都遵循非常简单的声明规则：

@fieldname value brief description

@param 和 @return 使用 : 将描述与其他参数分开，因为它们可以有可变数量的参数

Note

@param 可以具有以下变体：

@param name : description

@param name type : description

@param name type defvalue : description

并且 description 始终是可选的

在类范围内：

• @extends - 这个类扩展了什么类

在 class 的 property 中：

• @writeable - Can you modify 属性。

在 value 或 const 或 Var 范围内：

• @ftype - 常量类型（类似 TypeMask 的字符串或任何文本）

• @fvalue - 常量的值

在任何对象的范围内，您可以使用以下指令：

• @brief - 简短描述

• @parent - 范围引用（显示名称，如 parent.Object）

特殊指令

@resetscope - 退出所有范围（模块、函数）。

基本上是停止自动记录，直到进入下一个模块范围

@skipline - 解析中的skipnext行

.Func自动记录

If 函数在 中使用。Func（） 在同一个 cpp 文件中定义 - 它可以被自动记录。 不支持 lambda 或命名空间。 也不支持多行函数定义

int addTen(int val)
{
  return val+10;
}
...
.Func("bindFuncName", CppFuncName)  //将在文档中生成返回类型和参数 type 和 name

Doc-对象

Mutltiline (blocks)

@alert:

@alert
  这里有任何警报
alert@

Danger

这里有任何警报

@tip, @note, @seealso, ``@warning``的语法相同

Tip

提示！不错的提示！

Warning

警告！

Danger

使用此警报块可让读者注意严重威胁。

See also

在此处放置一些链接

Note

这是 note

---

@expand (aliases @spoiler, dropdown):

@spoiler My spoiler
  切换文本，可以是任何 RST（但不能是递归代码对象）

  preformat::

    一些代码或预先格式化文本
spoiler@

My spoiler

切换文本，可以是任何 RST（但不能是递归代码对象）

preformat:

一些代码或预先格式化文本

---

@code:

@code some_name lang
  watch indent
    will generate block
code@

some_name

  watch indent
    will generate block

配置要分析和构建的内容

您需要设置要解析的文件的放置位置以及文档的内容。 这是通过 .qdox 配置完成的 .qdox 配置为 JSON（支持 CPP 样式的单行注释）

.qdox

  [
  {
    "paths": ["prog/gameLibs/quirrel"], //文件夹或文件清单， 必需， 相对于配置
    "doc_chapter": "quirrel_gamelibs", //内部文件夹名称，必需
    "chapter_desc": "Docs for Quirrel modules extracted from source in gameLibs", //显示的标题，可选
    "chapter_title": "Quirrel Gamelibs Native Modules", //显示的标题，可选
    "extensions": [".cpp"], //可选，文件扩展名列表
    "exclude_dirs_re": [], //可选，应完全匹配以在递归搜索中排除目录的正则表达式列表
    "exclude_files_re": [], //可选，用于跳过文件的完全匹配正则表达式列表'
    "recursive": true //可选，对文件夹执行递归搜索'
  }
  ]

构建和测试 qdox

您需要安装 python 3.10+，并在路径中使用 python

安装:

pip install sphinx
pip install myst
pip install myst_parser
pip install sphinx_rtd_theme
pip install sphinx-autobuild

而不是在你的 dagor 文件夹中，你可以运行以下命令行:

python _docs/qdoc_main.py
sphinx-build -b html -d _docs/build/doctrees _docs/source _docs/build/html

（在构建 .qdox config 的文件夹中（有关详细信息，请参阅用法））

监视 cpp 文件、配置和 autorebuild 中的更改:

@start python _docs/watch.py
@start sphinx-autobuild --port 8080 _docs/source _docs/build/html

（在 .qdox 文件夹中，从源和配置启动 autorebuild rst）

要查看结果 - 使用浏览器打开``_docs/build/html/index.html``如果您手动构建（第一种方式），或者``localhost:8080``如果您启动 autobuild，请打开

ReStructuredText

任何不是 some 指令的 docline 都只是重组的文本

互联网上有很多 sphix rst 的 RTFM

强调: small emphasis

以下是您可以做的一些好事（请参阅 source/user-guid/qdox.rst 中的 source 以了解它是如何制作的）

inline let = function(){} wow

inline void function(){} here

例如，按行分隔文本：

---

彩色图标：，看看它。