Elixir Documentation Review#

Quick Reference#

Issue TypeReference@moduledoc, @doc quality, anti-patternsreferences/doc-quality.md@spec, @type, @typedoc coveragereferences/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

Function Documentation#

• All public functions have @doc
• All public functions have @spec
• @doc describes return values clearly
• Multi-clause functions documented before first clause
• Function head declared when arg names need clarification

Doctests#

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

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

Metadata#

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

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

Context-Sensitive Rules#

IssueFlag ONLY IFMissing @moduledocModule is public AND not a protocol implMissing @specFunction is public AND exportedMissing doctestsFunction is pure AND deterministicGeneric @docDoc restates function name without adding value

Gates (sequenced — do not skip)#

Work in order. Do not draft or ship a finding until the prior step passes.

1. Scope lock — Pass when: You listed the exact .ex/ .exs file paths (or Module names) under review; no vague “the project” scope.
2. Full-context read — Pass when: For each candidate issue, you read the full surrounding definition (all clauses for multi-clause functions; full @moduledoc block for module-level claims), not only a diff hunk or search snippet.
3. Evidence bundle — Pass when: Every draft finding uses the [FILE:LINE] ISSUE_TITLE header (line range allowed) and includes a verbatim quote or pointer to the @doc / @spec / doctest text in question. Module.function/arity may appear as supporting context but does not replace the [FILE:LINE] anchor. For “doctest fails” claims, Pass when: you cite mix test output for the relevant file or line, or the exact error string.
4. Protocol before report — Pass when: You loaded and followed review-verification-protocol (its Pre-Report checklist) before finalizing the issue list—not after.

When to Load References#

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