跳到正文

代码示例与 API 参考

提供可复制的最小示例,并用一致的字段解释参数、返回值和错误。

代码块与行内代码

给围栏代码块注明语言,例如 bash、ts 或 json。行内出现的命令、文件名、参数、环境变量和字面量用反引号包起来。命令与输出分别放进代码块,读者可以直接复制命令。

例如,在仓库根目录执行以下命令可以构建站点。

pnpm run build

构建完成后,检查项目根目录下生成的 .output/。

让示例可以复现

在示例前标明运行位置、依赖版本和必要配置。示例使用最小输入,保留能解释行为的调用。使用示例域名和占位值,并说明哪些值需要替换。注释说明意图、单位或边界条件。

只有片段时,说明要放入哪个文件、替换哪一段。引用输出时,保留读者需要核对的字段,并标明输出会随环境而变化的部分。

按代码的用途选择展示方式

代码的用途写法
在终端执行的命令注明运行目录,使用纯命令块
要放入文件的片段标注文件名和放置位置,说明依赖的导入
状态或输出单独展示输出,说明其中会变化的值
可互换的平台命令按代码组语法或分段组织

同一组示例用一致的变量、路径和配置值。验证时从预览页复制,在声明的环境运行一次,并对照成功输出与一个边界输入。完整的可执行示例可参考实用配方。

记录 API 行为

先给出调用签名和用途,再说明参数、返回值和错误。每个参数说明类型、是否必填、默认值、单位和有效范围中适用的字段。已有默认值示例时,核对代码是否实际使用了该默认值。

描述错误时,写清触发条件和可观察的错误码或消息。复杂对象适合用表格或独立小节记录字段。最后给出至少一个能体现典型行为的调用。

按条目类型使用更具体的函数与 HTTP API 参考、配置项参考或命令行参考。