为配置使用可查找的名称
标题写完整键名,例如 search.maxEntries,字段重名时附所属对象或配置文件。开头交代此键影响的行为和生效环境。列出类型、合法值、默认值、引入版本,以及改动后需要重新加载、构建还是重启。
示例工具的 search.maxEntries 可以这样记录。
| 字段 | 说明 |
|---|---|
| 类型 | 大于或等于 0 的整数 |
| 默认值 | 100 |
0 的含义 | 生成空索引 |
| 作用范围 | 构建时生成的搜索索引 |
| 生效方式 | 保存配置后重新构建 |
明确省略、覆盖和错误
说明省略配置时从哪里获得默认值。配置来自文件、环境变量和命令行时,给出实际实现的优先级。对象和数组发生合并时,说明替换、追加或按键覆盖的规则。如果配置对某平台或版本有效,写明读者能够辨认的触发条件。
无效值可能报错、产生告警或回退到默认值。按实际行为给出辨认方式。凡是会改变用户已有配置语义的默认值更新,都需要版本差异与迁移步骤。
将示例对齐到定义
{
"search": {
"maxEntries": 50
}
}
先说明示例放在哪个文件,再给出怎样确认实际值。如果项目从 JSDoc、类型或配置模式生成参考,修改生成输入,重新生成并对照默认值和合法范围。阅读页面与生成内容可以找到需要更新的文件。