跳到主要内容
版本：master

注释文档生成

本文档主要介绍注释生成文档的流程，gs中 efun/macro/enum 注释规范内容。便于开发者了解并使用本注释规范系统。本文档适用于，gs编译器开发者，gs注释及文档补充的同学。阅读完该文档你会了解到 gs中 efun/macro/enum 注释规范，以及 cicd 自动文档生成的流程。

1. 注释规范​

1.1 doxygen相关​

所有要生成文档的注释均需遵循doxygen的多行注释规范，代码中注释应类似如下形式:

/**
 * 多行注释
 * 这是第二行
 */

请检查 gs 目录下的 Doxyfile 文件以查看 doxygen 文档生成配置，其中需要注意的有以下几点：

  1. EXTRACT_ALL = NO 为避免未注释的代码段生成不必要的文档，此选项被关闭。
  2. HIDE_UNDOC_CLASSES = YES 用于避免不必要的文档生成，只有被规范注释类及其成员函数才会生成相关文档。
  3. HIDE_UNDOC_MEMBERS = YES 避免efun文档中出现非efun的class内部成员函数内容。

1.2 class 注释规范​

class 注释形式如下：

/**
 * @class cpp_class_name
 * @note gs_class_name
 * @brief Class introduction
 */
  • @class 此处应声明对应的C++类型名称 (必须)
    • 当此处声明的类名称与C++类型名称不符合时，doxygen无法正确将efun对应在相应class下
    • 以 system.core 对应类型为例，此处应为 @class EfunSystemCore
  • @note 此处应声明对应的gs类型名称 (必须)
    • 此处用于在文档转换时替换C++类型名称，由 ./tools/html2markdown.py 下的 python 代码实现转换
    • 以system.core 对应类型为例，此处应为 @note EfunSystemCore
  • @brief 此处应描述class大致功能及操作 (必须)
    • 此处用于解释class的大致功能及操作，同时打断 @note 声明
    • 当此项不存在直接在后续添加解释注释，文档生成进行类型名称替换时会带上 @note 声明的后续描述注释的内容，导致class名称错误

1.3 efun 注释规范​

efun注释形式如下：

/**
 * Efun describ 1
 * Efun describ 2
 * @param arg function argument introduction
 * @returns function return value introduction
 */
  • 注释首行后紧接函数描述信息，可以有多行内容
  • @param 此处应用于逐个解释函数参数功能及作用 (必须)
  • @return 或者 @returns 此处应用于解释返回值功能及作用 (必须)
  • @sesssin_key 此处应添加额外的注释内容，sesssin_key 应替换为如下选项中的一个 (可选)
    • note : 对应markdown中卡片 info
    • author :对应markdown中卡片 info
    • attention :对应markdown中卡片 warning
    • warning :对应markdown中卡片 warning
    • todo :对应markdown中卡片 info
    • pre :对应markdown中卡片 info
    • post :对应markdown中卡片 info
    • deprecated :对应markdown中卡片 danger
    • throws:对应markdown中卡片 danger
    • bug :对应markdown中卡片 danger

1.4 macro 注释规范​

macro注释形式如下：


/**
 * The macro expands to the GS version string.
 * \ingroup Macro
 * \page GS_VERSION
 */
  • 注释首行后紧接宏描述信息，可以有多行内容 (必须)
  • \ingroup Macro 用于将注释归类为 Macro 页面中 (必须)
  • \page MacroName 此处用于声明宏名称 (必须)

由于 doxygen 无法为非C++宏生成文档，实际声明了单独的页面组并在其中生成宏文档

1.5 enum 注释规范​

enum注释形式如下：

/**
 * \ingroup Enum
 * \page  TimeType
 * @brief Defines time formatting styles for time-related efuns.
 * - @c REGULAR_STYLE      Standard ctime format (e.g., "Tue May  8 12:42:34 2018").
 * - @c COMPACT_STYLE      Compact format with dashes (e.g., "2018-05-08-12:42:34").
 * - @c COMPACT_DATE       Date only (e.g., "2018-05-08").
 * - @c COMPACT_HMS        Time only (e.g., "12:42:34").
 * - @c NUMERIC_STYLE      Numeric format (e.g., "20180508124234").
 * - @c COMPACT_STYLE_STD  Compact format with space (e.g., "2018-05-08 12:42:34").
 */

  • \ingroup Enum 此处用于将注释归类为 Enum 页面中 (必须)
  • \page EnumType 此处用于声明 Enum 名称 (必须)
  • @brief 此处用于生成枚举作用描述 (可选)
  • - @c EnumItem 此处用于声明enum 成员及其作用 (必须)

由于 doxygen 无法为非C++枚举生成文档，实际声明了单独的页面组并在其中生成枚举文档

2. 自动文档生成流程​

此处简单介绍下自动化文档生成流程： 其简化流程大致如下：

  • -> cpp 注释
  • -> doxygen 生成 html 页面文档
  • -> html2markdown.py 负责文档英文翻译及将 html 页面转换为当前gs文档服务器支持的mdx格式

2.1 手动文档生成操作​

  • windows下命令行打开 gs 目录运行此命令: .\tools\doxygen\doxygen.exe
    • doxygen 会在 gs/doxy_gen_docs 目录下生成文档的html页面形式
  • windows下命令行打开 gs 目录运行此命令: python .\tools\html2markdown.py
    • html2markdown 脚本会在 gs/docs/auto_gen 目录下自动生成转换和翻译后的mdx文档
  • 检查 gs/docs/auto_gen 目录下自动生成的转换及翻译文档

2.2 cicd 自动操作​

cicd 自动化流程中除自动化了上述操作外，

  • cicd 中 build_docs 中为文档生成阶段，需手动点击cicd按钮触发。
  • 会为文档生成新的 docs-update-${CI_COMMIT_SHORT_SHA}-${CI_PIPELINE_ID} 分支
  • 将文档添加进入分支提交中，并自动创建 Merge Request。
  • 应在 Merge Request 中审查生成的中文文档。

2.3 html2markdown.py 注意实现​

  • 翻译实际使用 OpenAI 的接口生成AI翻译
    • 由于会消耗 OpenAI 的token本地运行需要输入个人的 OpenAI token
    • cicd 环境变量中 OPENAI_TOKEN 中为 @liangyb 提供的 OpenAI token
    • 若无个人 Token 请去 OpenAI 获取或检查 gs cicd 的 OPENAI_TOKEN 环境变量
  • ./tools/translation_cache.json 为翻译缓存
    • 由于 OpenAI 翻译需等待网络请求速度较慢，且会消耗 token 且大部分的注释在单个提交中不会改变，翻译时会尝试先从本地缓存获取翻译