模块文档编写指南

在市场发布模块时需要提供对应的模块使用文档，以便用户更好地了解和使用模块。本文介绍如何编写 DolphinDB 模块的使用文档，提升文档编写效率和审核通过率。

1. 模块使用文档

注：
请用 markdown 格式编写文档。

一篇完整的模块使用文档需包含以下内容：文档标题、模块介绍、第三方库/模块介绍（可选）、安装模块、接口介绍、使用示例、版本说明、常见问题（可选）和附录（可选）。除可选章节外，其他章节必须包含且按照给定的顺序依次编写。文中标题级别最多为三级。可直接下载文档模板进行编写，下表介绍每个章节的编写细则并提供示例：

章节 编写细则
文档标题

一级标题。固定为“XXX 模块使用说明”。

注：

XXX 必须是模块文件首行声明的模块名称，大小写保持一致，模块名推荐采用大驼峰形式。
模块介绍

二级标题。介绍模块的开发背景、主要功能、应用场景。

提示：

测试 DolphinDB 数据库性能时，往往需要在短时间内写入大量结构规范、分布可控的测试数据。为满足这一需求，DolphinDB 开发了 MockData 模块。该模块用于快速模拟生成各类金融业务数据及对应的库表结构，避免对真实业务数据的依赖，提高测试和验证工作的效率与可重复性。

目前，MockData 模块支持多种常见金融数据类型，包括股票数据（快照、逐笔委托、逐笔成交等）、期权数据、期货数据、银行间债券数据以及因子库数据。该模块主要适用于性能和压力测试、功能验证与回归测试、方案演示，以及开发调试等场景。
第三方模块/插件介绍

二级标题。列举模块依赖的其他模块/插件，介绍其用途。

提示：

easyNSQ 模块依赖于 NSQ 插件，请确保先加载 NSQ 插件，再加载 easyNSQ 模块。通过该插件能够获取上海和深圳市场的行情。插件的安装和使用请参考NSQ 。
安装模块 二级标题。介绍模块适用的 DolphinDB 版本以及模块安装步骤。完整示例请参考文档模板。
接口介绍

二级标题。严格按照以下顺序介绍接口：接口名称、语法、详情、参数、返回值、例子。完整示例请参考文档模板。

注：
  • 接口名称：提供接口的名称，并设置为三级标题，其余章节标题加粗即可。
  • 语法：包含参数的接口名，设置为行内代码块。例：getAllLicenses()。
  • 详情：介绍接口的功能、使用限制、注意事项等。
  • 参数：介绍参数的数据类型和形式、是否可选、含义、可选值、默认值等。没有参数则填“无”。列举参数时无需使用列表格式，换行即可。
  • 返回值：介绍返回数据的类型和形式。没有返回值则填“无”。
  • 例子：提供接口调用的示例以及返回结果（如有）。除代码示例外，还需要相应的文字说明，且示例需要符合实际的应用场景。
使用示例

二级标题。不同于接口介绍中针对单个接口提供的示例，此处的使用示例需结合多个接口或其他功能展示如何实现特定的应用场景。

注：

编写使用示例时，遵循先阐述工作流再给出操作步骤+代码的原则。完整的示例请参考文档模板。
版本说明

二级标题。根据发布内容的不同版本说明分为三种类型：新功能、功能优化和故障修复。除此之外，也可以提供兼容性说明。

注：

每条说明的末尾需要添加对应的版本号。

  • 新功能：说明新增的功能，主要是新增函数、参数的说明。

    例：新增函数 setLogLevel 和 getLogLevel，用于设置和获取输出日志的等级。（1.0.4）

  • 功能优化：说明优化的功能点及其改进效果，主要是性能或者使用方法的优化。

    例：提升逐笔数据的接收处理效率。（1.0.1）

  • 故障修复：描述修复的具体问题，明确指出问题的影响范围或场景。

    例：修复订阅逐笔合并数据时，跨天后日期不更新的问题。（1.0.1）

  • 兼容性说明：描述已发布功能的兼容性情况。

    例：删除了原有冗余函数 30 余个，如果情况特殊需要用到之前函数，请联系技术支持获取带有全部函数的插件 txt 文件。（1.0.1）
常见问题

二级标题。列举用户使用模块时可能会遇到的问题并提供解决方法。

注：

编写常见问题时，首先提取问题的核心部分作为三级标题，如“模拟数据生成返回 0 行记录怎么办？”，然后在正文中简述问题出现的场景、提供示例代码/报错等，最后给出相应的解决方法。完整的示例请参考文档模板。
附录

二级标题。附录中可包含以下内容，均以下载链接的形式提供：

  • 完整的示例代码、测试数据集。
  • 性能/正确性测试结果。

2. 文档样式指南

  • 无需添加标题编号，如 1.1 等。
  • 统一使用中文标点，特殊情况除外，如示例代码中的标点。
  • 中文中夹杂英文名称时，英文前后加空格。例如，“安装 DolphinDB 的 Mock 模块。”
  • 接口名使用行内代码块包裹。例如，getTableDiskUsage。
  • 函数参数和系统配置项（如有）都用斜体。例如，tableName。
  • DolphinDB 的数据类型全部大写。例如，INT。
  • 文件路径使用斜体。例如，server/clusterDemo/data/datanode1。
  • 多点枚举：
    • 无序列表：列表项之间无顺序关系。
    • 有序列表：列表项之间存在顺序关系。