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 代码的简要示例： .. code-block:: cpp :caption: 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 `` 或 ``///@page `` 放在文件的某个地方， 因为没有 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``. 当 ``@`` 出现 （如 ``code@``, ``tip@``,等） 或注释结束时，这些对象会关闭它们的作用域。 这些对象可以在任何范围内，因为它们只是添加了创建 rst 的简单方法（见下文） 每个对象 - 容器或叶类型 - 都可以使用 module 的 scope 来定义。 ``@class myModule/MyClass`` 将设置 MyClass 在 myModule 中。 函数、表和类可以定义为一个模块： ``@class DataBlock = DataBlock`` 将描述导出类 DataBlock 的模块。 在函数作用域（以及 operator 和 ctor）中，您可以使用以下指令： * ``@paramsnum`` - 参数数量的 integer（在 cpp 中称为 paramscheck）。 如果为负数 - 表示可以使用至少该数量的参数调用函数，但也可以使用更多参数调用该函数。 * ``@kwarged`` - 表示函数参数应通过 table 提供。喜欢： :sq:`function foo({argument=1, arg2=2})` * ``@typemask`` - string 替换为 typemask 的 String。看`documentation `_ * ``@vargved`` - 表示函数可以具有变量参数 count * ``@param`` - 应该是 ``@param : 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 或命名空间。 也不支持多行函数定义 .. code-block:: cpp 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:: 使用此警报块可让读者注意严重威胁。 .. seealso:: 在此处放置一些链接 .. note:: 这是 note -------- ``@expand`` (aliases ``@spoiler``, ``dropdown``):: @spoiler My spoiler 切换文本，可以是任何 RST（但不能是递归代码对象） preformat:: 一些代码或预先格式化文本 spoiler@ .. dropdown:: My spoiler 切换文本，可以是任何 RST（但不能是递归代码对象） preformat:: 一些代码或预先格式化文本 -------- ``@code``:: @code some_name lang watch indent will generate block code@ .. code-block:: lang :caption: some_name watch indent will generate block 配置要分析和构建的内容 --------------------------------------- 您需要设置要解析的文件的放置位置以及文档的内容。 这是通过 .qdox 配置完成的 .qdox 配置为 JSON（支持 CPP 样式的单行注释） .. code-block:: cpp :caption: .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 :sq:`let = function(){}` wow inline :cpp:`void function(){}` here 例如，按行分隔文本： ------------- 彩色图标：:octicon:`report;1em;sd-text-info`，看看它。