2.5 KiB
2.5 KiB
TASK-03 编写语法与 API 参考
适用：声明、表达式、关键字、函数或 UI 组件的精确查询页。读者已有目标，需要判断形式、输入、约束和效果。
必读：语义契约、语言核对地图、DOC-008、DOC-012、DOC-013、DOC-015。使用TPL-03。
先收集规则依据
列出对象的主定义、形式文法、规范状态和现有例子。对每个准备加入的字段写出依据。当前没定义默认值就写未定义，不凭常见库经验补一个合理值。
若一页既承担教学又承担查询，开头可以保留最小定义，参考小节应能独立找到。避免先读十段设计理由才能看到形式。
根据对象选择字段
| 对象 | 重点字段 | 不应硬填 |
|---|---|---|
| use | 完整 key、位置、引用作用、名称可见性条件 | 函数式返回值 |
| function | 参数与结果、函数体形式、类型与依赖 | 未定义的 async 或异常关键字 |
| class | 字段、类型、已有结构约束 | 自动构造方法、get、持久化规则 |
| UI 组件 | 参数、子节点、排列与已知默认值 | 未规定的 CSS 单位或事件系统 |
参数有名称、类型、意义、默认值与范围时可以制表。只知道其中部分就保留真实信息，说明未定的关键项；表格整齐不是补造 API 的理由。
核对形式与语义
从文本到文法：可选、重复、数量、顺序是否有对应形式？从文法到文本：每个公开结构是否有含义、条件和结果说明？
不复制一整套 EBNF 到每页。正文可展示阅读友好的基本形式，精确产生式链接集中附录。需要修正文法时更新它，并检索受影响的例子与状态。
正例与边界
提供一个最小正例，解释其外部上下文。再选择一项最容易误解的边界。例如 use 的 key 与所属 key 不同；导入不等于获得访问权限。
错误示例说明违反哪条约束以及怎样修正。错误码、错误文本尚未定义时不模拟实现输出。
验收
让读者从页中直接找到：在哪里写、怎样写、输入要求、成功效果、关键边界和状态。不能必须返回聊天记录才能知道哪个字段只是提案。
完整成稿与写作说明见EX-02。