跳到正文

配置项参考

记录字段路径、类型、有效范围、默认值、优先级和生效时机。

为配置使用可查找的名称

标题写完整键名,例如 search.maxEntries,字段重名时附所属对象或配置文件。开头交代此键影响的行为和生效环境。列出类型、合法值、默认值、引入版本,以及改动后需要重新加载、构建还是重启。

示例工具的 search.maxEntries 可以这样记录。

字段说明
类型大于或等于 0 的整数
默认值100
0 的含义生成空索引
作用范围构建时生成的搜索索引
生效方式保存配置后重新构建

明确省略、覆盖和错误

说明省略配置时从哪里获得默认值。配置来自文件、环境变量和命令行时,给出实际实现的优先级。对象和数组发生合并时,说明替换、追加或按键覆盖的规则。如果配置对某平台或版本有效,写明读者能够辨认的触发条件。

无效值可能报错、产生告警或回退到默认值。按实际行为给出辨认方式。凡是会改变用户已有配置语义的默认值更新,都需要版本差异与迁移步骤。

将示例对齐到定义

{
  "search": {
    "maxEntries": 50
  }
}

先说明示例放在哪个文件,再给出怎样确认实际值。如果项目从 JSDoc、类型或配置模式生成参考,修改生成输入,重新生成并对照默认值和合法范围。阅读页面与生成内容可以找到需要更新的文件。