关于 elixir-docs-review
用于审查 Elixir 文档、规格声明和 doctest 的技能，提供检查清单、情境规则与证据门槛，重点覆盖公开 API。
主要功能
- 01模块与函数文档检查
- 02公开 API 规格覆盖检查
- 03doctest 适用性与执行检查
- 04交叉引用和元数据检查
- 05基于证据的审查门槛
适用场景
- 01审查公开 Elixir 模块的文档
- 02检查导出函数是否有 @doc 和 @spec
- 03评估纯函数的 doctest 覆盖情况
安装
复制下面的命令，在终端中运行。
$
npx skills add https:/安装后在 Claude Code 中输入/elixir-docs-review确认已加载。
附带文件references/doc-quality.mdreferences/spec-coverage.md
详细介绍
Elixir 文档审查
快速参考
| 问题类型 | 参考资料 |
|---|---|
| @moduledoc、@doc 质量、反模式 | references/doc-quality.md |
| @spec、@type、@typedoc 覆盖情况 | references/spec-coverage.md |
审查清单
模块文档
- 所有公开模块都有 @moduledoc
- 首行摘要简洁明了（一行，供工具用作摘要）
- 适当时，@moduledoc 包含 ## Examples
- @moduledoc false 仅用于内部模块／实现模块
函数文档
- 所有公开函数都有 @doc
- 所有公开函数都有 @spec
- @doc 清晰描述返回值
- 多子句函数在第一个子句之前编写文档
- 需要澄清参数名称时，声明函数头
Doctest
- 纯函数、确定性函数有 doctest
- 有副作用的操作（数据库、HTTP 等）不写 doctest
- Doctest 确实会运行（模块已包含在测试文件中）
交叉引用
- 模块引用使用反引号自动链接（
MyModule） - 函数引用使用正确的元数格式（
function/2） - 类型引用使用 t: 前缀（
t:typename/0） - 有自动链接时，不使用纯文本引用
元数据
- 新增公开 API 时添加 @since 注解
- 适当时添加 @deprecated，并提供迁移指引
有效模式（不要标记）
- 回调实现上的 @doc false — 已在行为层级编写文档
- 协议实现上的 @doc false — 协议文档已说明其意图
- 私有函数缺少 @spec — 内部函数的 @spec 可选
- 简单实用工具模块的 @moduledoc 简短且不含 ## Examples — 并非每个模块都需要示例
- 使用 @impl true 且没有单独的 @doc — 继承行为文档
上下文相关规则
| 问题 | 仅在以下情况标记 |
|---|---|
| 缺少 @moduledoc | 模块是公开的，且不是协议实现 |
| 缺少 @spec | 函数是公开且已导出的 |
| 缺少 doctest | 函数是纯函数且具有确定性 |
| 泛泛的 @doc | 文档只是重述函数名称，没有提供额外价值 |
检查关卡（按顺序执行，不要跳过）
按顺序进行。前一步未通过前，不要起草或提交问题发现。
- 锁定范围 — 通过条件： 列出正在审查的确切
.ex/.exs文件路径（或Module名称）；不得使用“整个项目”这类模糊范围。 - 阅读完整上下文 — 通过条件： 对每个候选问题，都阅读完整的相关定义（多子句函数的所有子句；模块级问题需阅读完整的
@moduledoc块），不能只看差异片段或搜索结果。 - 证据组合 — 通过条件： 每条待提交的问题发现都使用
[FILE:LINE] ISSUE_TITLE标题（允许行号范围），并且包含相关@doc/@spec/ doctest 文本的原文引述或指向。Module.function/arity可作为补充上下文，但不能替代[FILE:LINE]定位信息。对于“doctest 失败”的问题，通过条件： 引用相关文件或行的mix test输出，或提供确切的错误字符串。 - 先遵循协议再报告 — 通过条件： 在确定问题清单之前，加载并遵循 review-verification-protocol（其报告前检查清单），而不是事后执行。
何时加载参考资料
- 审查 @moduledoc 或 @doc 质量、发现反模式时 -> doc-quality.md
- 审查 @spec、@type 或 @typedoc 覆盖情况时 -> spec-coverage.md
评论
支持 Markdown