用途:按 ExDoc 规范审查 Elixir 项目的文档完整性、质量与最佳实践,覆盖模块文档、函数文档、规格与 doctest、交叉引用及元数据。
主要能力与检查项:
- 模块文档:所有公共模块是否有 @moduledoc;首行摘要是否简洁(工具常将其用作摘要);适当包含 ## Examples;@moduledoc false 仅用于内部实现模块。
- 函数文档:公共函数是否有 @doc 与 @spec;@doc 是否清楚说明返回值;多子句函数是否在首个子句前统一文档;参数名不清时是否声明函数头。
- Doctest:纯函数、确定性函数是否有 doctest;有副作用操作(数据库、HTTP 等)不应写 doctest;doctest 是否真的被运行(模块需包含在测试文件中)。
- 交叉引用:模块引用用反引号自动链接(如 MyModule);函数引用用正确 arity 格式(function/2);类型引用用 t: 前缀(t:typename/0);能用自动链接时不用纯文本引用。
- 元数据:新增公共 API 是否标注 @since;废弃项是否用 @deprecated 并给出迁移指引。
使用方式:先锁定审查范围,列出具体的 .ex/.exs 文件路径或模块名,不要用模糊的“整个项目”;逐条候选问题读取完整上下文(多子句看全部子句,模块级结论看整个 @moduledoc 块),而非仅看 diff 或搜索片段;每条发现用 [FILE:LINE] 标题并附 @doc/@spec/doctest 原文引用;对“doctest 失败”的断言需给出相关文件的 mix test 输出或确切错误字符串;定稿前加载并遵循 review-verification-protocol 的清单。
适用场景:审查文档质量、规格覆盖率、doctest 正确性,以及排查文档反模式。加载参考:审 @moduledoc/@doc 质量与反模式时读 references/doc-quality.md;审 @spec/@type/@typedoc 覆盖率时读 references/spec-coverage.md。
限制:资料未提供该技能的具体安装或集成方式、支持版本、输出格式与依赖,均暂未提供。