Back to Details

elixir-docs-review

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Elixir Documentation Review

Elixir文档审查

Quick Reference

快速参考

Issue Type	Reference
@moduledoc, @doc quality, anti-patterns	references/doc-quality.md
@spec, @type, @typedoc coverage	references/spec-coverage.md

问题类型	参考文档
@moduledoc、@doc质量、反模式	references/doc-quality.md
@spec、@type、@typedoc覆盖率	references/spec-coverage.md

Review Checklist

审查清单

Module Documentation

模块文档

All public modules have @moduledoc
First-line summary is concise (one line, used by tools as summary)
@moduledoc includes ## Examples where appropriate
@moduledoc false only on internal/implementation modules

所有公共模块都包含@moduledoc
首行摘要简洁（单行，供工具用作摘要）
合适的情况下@moduledoc中包含## 示例部分
仅在内部/实现模块上使用@moduledoc false

Function Documentation

函数文档

Doctests

Doctest测试

Doctests present for pure, deterministic functions
No doctests for side-effectful operations (DB, HTTP, etc.)
Doctests actually run (module included in test file)

纯函数、确定性函数都配有doctest
有副作用的操作（数据库、HTTP等）不添加doctest
Doctest可实际运行（模块已包含在测试文件中）

Cross-References

交叉引用

Module references use backtick auto-linking (
```
MyModule
```
)
Function refs use proper arity format (
```
function/2
```
)
Type refs use t: prefix (
```
t:typename/0
```
)
No plain-text references where auto-links are possible

模块引用使用反引号自动链接（
```
MyModule
```
）
函数引用使用正确的元数格式（
```
function/2
```
）
类型引用使用t:前缀（
```
t:typename/0
```
）
可使用自动链接的地方不使用纯文本引用

Metadata

元数据

@since annotations on new public API additions
@deprecated with migration guidance where appropriate

新增的公共API添加@since注解
合适的情况下为废弃API添加@deprecated注解并提供迁移指南

Valid Patterns (Do NOT Flag)

有效模式（无需标记）

@doc false on callback implementations - Documented at behaviour level
@doc false on protocol implementations - Protocol docs cover the intent
Missing @spec on private functions - @spec optional for internals
Short @moduledoc without ## Examples on simple utility modules - Not every module needs examples
Using @impl true without separate @doc - Inherits documentation from behaviour

回调实现上的@doc false - 已在行为（behaviour）层面进行文档说明
协议实现上的@doc false - 协议文档已涵盖其用途
私有函数缺少@spec - @spec对内部函数是可选的
简单工具模块的@moduledoc简短且无## 示例 - 并非所有模块都需要示例
使用@impl true但未单独添加@doc - 从行为（behaviour）继承文档

Context-Sensitive Rules

上下文相关规则

Issue	Flag ONLY IF
Missing @moduledoc	Module is public AND not a protocol impl
Missing @spec	Function is public AND exported
Missing doctests	Function is pure AND deterministic
Generic @doc	Doc restates function name without adding value

问题	仅在以下情况标记
缺少@moduledoc	模块是公共模块且不是协议实现
缺少@spec	函数是公共函数且已导出
缺少doctest	函数是纯函数且具有确定性
通用化@doc	文档仅重复函数名称，未添加任何有效信息

When to Load References

何时加载参考文档

Reviewing @moduledoc or @doc quality, seeing anti-patterns -> doc-quality.md
Reviewing @spec, @type, or @typedoc coverage -> spec-coverage.md

审查@moduledoc或@doc质量、发现反模式时 → 加载doc-quality.md
审查@spec、@type或@typedoc覆盖率时 → 加载spec-coverage.md

Before Submitting Findings

提交结果前需完成

Load and follow review-verification-protocol before reporting any issue.

报告任何问题前，请加载并遵循审查验证协议。