Elixir Documentation Review

Quick Reference

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

When to Load References

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

Before Submitting Findings

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