企业官网建设流程全解析

• 编程语言
• 语言运行时
• 标准库
• 垃圾回收
• 并发编程

本篇技术文章基于仓颉（Cangjie）运行时与标准库仓库中的接口 API 文档模板 xxx_package_interfaces.md，系统讲解标准库 interface 类型 API 文档的目录位置、编排顺序、必写字段与 extend 扩展小节的写法。读完本文，你可以按模板独立编写一个标准库包的接口 API 文档，并能用 std.convert 包的真实接口文档与 formattable.cj、parsable.cj 源码相互印证模板规则的落地方式。

模板在标准库文档体系中的位置

接口 API 文档模板位于标准库文档贡献模板目录下的xxx_package_api子目录中，与类、函数、枚举等文档模板并列：

stdlib/doc/contribute/template/ └── libs_template/ ├── summary.md // 文档目录注册文件 └── std/ ├── std_module_overview.md // 标准库概述（包汇总页） └── xxx/ // 包名占位符 ├── xxx_package_api/ // 本包内各类型 API 文档 │ ├── xxx_package_classes.md │ ├── xxx_package_funcs.md │ ├── xxx_package_interfaces.md // 本模板：interface 类型 API 文档 │ └── ... ├── xxx_samples/sample1.md // 本包示例教程 └── xxx_package_overview.md // 包概述、API 汇总页

按照 库 API 文档写作指导 中给出的文档层级结构，libs/std/xxx/包目录下应包含：包内各类型 API 文档（xxx_package_api/）、示例教程（xxx_samples/）以及包概述xxx_package_overview.md；若包内需要配图，则在包目录下新建figures文件夹。所有文档还需在 summary.md 目录文件中“注册”后，才会最终呈现在构建出的文档包中，其中每个包下均有独立的[接口](https://link.gitcode.com/i/579f1b6b6fc6aa86aff98c5808b7d075)条目。

模板总览：interface 文档的五条编排规则

模板开篇以引用块给出五条说明（对应模板文件 第 1～13 行），是整篇接口文档的总纲：

1. 接口（interface）按字母顺序展示；

2. 对于 interface 内的子 API，按**属性（prop）、函数（func）、操作符函数（operator func）**的类型顺序展示；

3. interface 的各子类型内部，子 API 按字母顺序排列；

4. 若子类型中重写了父类型的函数，需要在文档中体现该 function；

5. 文档中提到其他 API 时，都必须使用超链接链过去，模板给出的示例写法为：

   ArrayList

   即“呈现文本 + 目标文档相对路径 + 目标标题锚点”的形式，保证 API 之间的交叉引用可跳转。

接口主体部分：interface Interface1 的必写字段

模板为每个接口定义了统一的 H2 小节骨架，以## interface Interface1为例，包含三个【必写】要素：

（1）定义声明：接口的声明代码应包含其全部属性和函数，模板给出的占位声明为：

public interface Interface1 { prop property1: dtype func function1() operator func ==(Ordering) }

（2）功能：参考 功能模块写作规范。写作指导要求功能部分首先用一句话（动宾短语，而非“该 API 实现了…”句式）总结 API 干了什么、返回什么值，然后可展开原理、使用场景与约束。

（3）示例：参考 示例代码规范及格式要求。示例代码需典型、完整且可正确运行，展示输出结果，import 路径正确，正例不能有 warning/error。

主体之后依次列出接口的子 API 小节，模板中以占位形式给出三类子 API 及其参考去向：

子 API 小节：prop / func / operator func

• ### prop property1：参考 属性模板（即类文档模板中的属性写法：定义声明 + 功能 + 类型超链接）；
• ### func function1()与### operator func ==(Ordering)：均参考 函数内容模板。函数模板的字段结构为：定义声明（与源码一致的 cangjie 代码块）→【必写】功能 →【可选】说明/注意/警告 →【涉及必写】参数 →【涉及必写】返回值 →【可选】异常 →【必写】示例，并标注各字段与 写作指导 中对应章节的映射关系。

这一安排使得接口文档不必重复发明格式，而是复用类文档的属性写法与函数文档模板，保证整个xxx_package_api/目录下各类型文档格式统一。

extend 扩展小节：为类型补全接口实现

模板在接口主体之后给出了两个### extend小节，用于文档化“某类型通过扩展实现该接口”的情形，这正是仓颉标准库中接口落地的主要方式。

情况一：### extend BigInteger<T> <: Interface1（为泛型类型扩展实现接口）：

• 【必写】定义声明，模板以...占位，实际应写出extend ... <: Interface1的完整声明代码块；

• 【必写】功能，一句话说明该扩展的作用；

• 【涉及必写】父类型，以超链接列回本文档的接口标题：

  - [Interface1](#interface-interface1)

• #### func a()：给出该扩展实现的子函数文档；

• #### xxx：模板在此处注明“参考 库文档写作指导及注意事项 libs/api_docs_guide.md”。需要说明的是，在当前仓库快照中未检索到api_docs_guide.md这个文件（模板中的该引用属于悬空链接），实际的写作规范以 template/overview.md 为准。

情况二：### extend Time <: Interface1：结构完全同上（定义声明 + 功能 + 父类型 +#### func b()），以“模板同 Interface1 的 extend 小节”收尾，并同样要求在接口文档末尾为下一个接口## interface Interface2复用同一套模板。

模板对 extend 小节的要求与写作指导中“扩展 (extend) API 的写法”一节相互呼应。其中与 interface 文档直接相关的是情况 3：为类型 A 扩展接口 B，且 B 在本包定义，文档组织方式正是本模板所示：

## interface B ### func b() ### extend A <: B #### func b() #### func c()

即接口 B 作为 H2 主体，extend A <: B作为其下的 H3 小节，扩展实现的具体方法作为 H4 小节逐一文档化；当接口方法带有默认实现时，默认实现也需在扩展小节中一并给出（参考 类文档模板中的扩展示例）。

实战印证：std.convert 包如何落地该模板

模板中的Interface1、BigInteger<T>都是占位符，仓库中 std.convert 包的接口文档 是严格按此模板成文的实例，可逐条对照验证模板规则。

接口主体（对应模板## interface Interface1）。convert 包文档以## interface Formattable开头，声明代码块与 formattable.cj 源码 完全一致：

public interface Formattable { func format(fmt: String): String }

其后紧跟功能描述（“该接口定义了格式化函数，即根据格式化参数将指定类型实例转换为对应格式的字符串”）以及指向 convert 包功能介绍 的超链接——对应模板“功能”与“超链接”两条规则。

子 API 小节（对应### func function1()）。文档接着给出### func format(String)，按函数模板顺序包含：定义声明、功能、参数（fmt: String带类型超链接）、返回值，与 函数模板 的字段一一对应。

extend 小节（对应### extend Time <: Interface1）。文档为Float16、Float32、Int64、UInt64、Rune等基础类型逐一给出### extend Xxx <: Formattable小节，每节均含定义声明（如extend Float16 <: Formattable）、功能、父类型超链接列表，以及 H4 级别的#### func format(String)完整文档（声明/参数/返回值/异常/示例）。示例代码上方还带有<!-- verify -->看护标签并附运行结果，正是 写作指导中“示例看护标签说明” 的要求。

源码侧印证。在 formattable.cj 中，每个extend Xxx <: Formattable扩展都实现了public func format(fmt: String): String，例如 extend Int64 <: Formattable 先校验格式化串再调用内部parser解析出Flags/Width/Precision/specifier并交给FormatSpecifier完成格式化；parsable.cj 中则定义了泛型接口Parsable<T>（L26-L47，含static func parse与static func tryParse）以及RadixConvertible接口，并通过extend Int8 <: Parsable<Int8>（L143-L207）等扩展为各整数、浮点类型提供实现——文档中的extend Xxx <: Parsable<Xxx>小节即与这些源码扩展一一对应，体现了模板规则第 4 条“重写/实现的函数必须在文档中体现”的约束。

与包概述页的衔接

接口文档并非孤立存在。按照 包概述模板，xxx_package_overview.md中的“API 列表”按“常量&变量、函数、类型别名、接口、类、枚举、结构体、宏、异常类”的类别顺序列表格，每种类别一个列表、表内 API 按字母顺序排列（与接口文档内顺序一致）；“接口”类别的表格第一列为 API 名称 + 参数类型并链接到接口文档标题，第二列取该接口功能描述的第一句话。convert 包的 包概述 中即有Formattable、Parsable<T>、RadixConvertible<T>三行指向接口文档锚点的表格，验证了概述页与接口文档之间的锚点链接约定。

小结

xxx_package_interfaces.md 是仓颉标准库文档体系中 interface 类型 API 文档的标准模板：它规定了接口按字母顺序组织、子 API 按 prop/func/operator func 类型序与字母序排列、重写函数必须体现、跨 API 引用必须超链接等核心规则，并以“定义声明 + 功能 + 示例”三必写字段定义接口主体，以extend X <: Interface小节承接扩展实现。结合 template/overview.md 的通用写作规范与 std.convert 包接口文档 及其 formattable.cj、parsable.cj 源码，可以完整复现“从模板到成文”的过程，为编写其他标准库包的接口 API 文档提供可直接参照的样板。

• 编程语言
• 语言运行时
• 标准库
• 垃圾回收
• 并发编程