用途：为 Motoko 源文件中每个公开声明添加三斜线（///）文档注释，让 mo-doc 渲染出有意义的文档页面。适用于用户要求“添加文档字符串”“记录公开 API”“生成文档”，或库发布（如 MOPS）前审查润色，以及新增公开符号后发现 docs/ 中缺失条目时。
需文档化的「公开对象」：public type、public let、public func、public class，模块自身（module { ... }），公开 class 内的 public let/public var/public func 成员，以及嵌套公开模块（递归处理）。私有声明（无 public 的 func/let/class）和辅助类型不应加 ///，它们不出现在 mo-doc 输出里。
详尽程度：src/internal/（某些包用 src/private/）内可简短，一句话说明即可；src/ 其他位置属公开 API，必须详尽，涵盖参数单位与格式、尺寸/范围约束、返回值语义、完整失败行为（Traps/Errors 段落）和可运行示例。
格式：/// 行按 Markdown 解析并附加到下一个声明。首行为简短祈使式摘要并以句号结尾，段落间用一个空 /// 行分隔，参数名与类型用反引号。代码块用 motoko 围栏；依赖模块导入头时用 motoko include=import，并可为模块级文档定义一次 ```motoko name=import 命名导入块。这两个注解由外部 doctest 运行器消费，mo-doc 仅原样透传；项目不跑 doctest 时可省略。
模块级注释位置：必须位于文件最顶端、import 语句之前，与 imports 及 module { ... } 行之间各留一个空行；放在 imports 与 module 之间会被静默忽略，渲染页面无描述。所有 .mo 文件都应有顶部模块级 ///；mixin 文件虽当前被 mo-doc 跳过，仍须置于顶端。命名模块（module Name { ... }）同样规则，注释放文件开头而非 module 行前。
每个声明的 /// 紧贴声明上方，与声明之间不留空行；若有旧版 // 注释，/// 块放在旧注释之上。
错误与 Trap 行为为必需内容：需扫描实现中的 Runtime.trap/Debug.trap/Prim.trap、assert、非穷尽模式匹配、隐式 trap（越界索引、Nat 下溢、除零、Option.unwrap）、显式错误返回（?T 的 null、Result 的 #err、variant 返回）。对每种失败写明触发条件（用面向用户的措辞）与结果，不可恢复失败使用大写“Traps”措辞置于示例之后。纯函数可显式写“Never traps.”。
常见陷阱：apply_patch 中多行内容写真实换行，勿用字面 \n；上下文过短可能插入函数体中部，插入后用 mo-doc 或 moc --check 检查，出现 syntax error [M0001], unexpected token 'import' 即说明放错位置；class 描述块应紧贴 public class Name(...) 上一行以置顶显示；再导出类型仍需一行 /// 以免显示“(no description)”；勿给非 public 声明加注释；命名模块同样顶部放置；不熟悉的方法分发参数（如 self : [var T]）和隐式参数须原样保留；记录类型成员建议在类型上方单块内逐一说明而非逐行 ///。
工作流：用 grep -RInE "public (type|func|class|let)" src 清点公开声明；逐文件补顶部模块级块与各公开声明的 ///；递归处理嵌套公开成员；用 awk 审计遗漏（可移植性上使用 [ \t]+ 而非 [[:space:]]+/\b，BSD/macOS awk 会静默失败）；注意旧版注释与块注释内的假阳性。生成文档时需先建目录（mo-doc 不会自建嵌套输出目录）：mkdir -p docs $(find src -mindepth 1 -type d | sed 's|^src|docs|')，再运行 mo-doc --source src --output docs --format html；无输出即成功，注意 Sys_error 缺目录与 Skipping 语法错误两类失败。最后抽查 docs/index.html 与各模块页面。
其它：常量表（如 SHA256 K00..K63、SHA512 K00..K79）每个 public let 都需独立 /// 行，可读入整体重写；模块级 /// 承载共享上下文。低层辅助函数一句话说明字节序、宽度与偏移语义；领域类型注明定义格式的规范或 BIP 并链接。