ex_doc

ExDoc documentation validation plugin that checks for documentation issues before commits

Installation

npx claude-plugins install @bradleygolden/elixir/ex_doc

Contents

Folders: hooks, scripts

Files: CHANGELOG.md, README.md

Documentation

ExDoc documentation validation plugin for Claude Code that ensures documentation quality by checking for issues before commits.

Overview

This plugin integrates ExDoc’s documentation validation into your development workflow by running mix docs --warnings-as-errors before git commits. It prevents commits when documentation issues are detected, helping maintain high documentation quality in your Elixir projects.

Installation

/plugin marketplace add github:bradleygolden/claude-marketplace-elixir
/plugin install ex_doc@elixir

Features

Pre-Commit Documentation Validation

Automatically runs before git commit commands to validate documentation quality:

• Undefined reference detection - Catches references to non-existent modules, functions, types, or callbacks
• Broken link detection - Identifies links to missing files in documentation
• Configuration validation - Ensures valid ExDoc configuration
• Asset validation - Checks image formats and other assets
• Blocks commits - Prevents committing code with documentation issues

How It Works

PreToolUse Hook (Blocking)

The plugin uses a single PreToolUse hook that:

1. Triggers before git commit commands execute
2. Detects if the project uses ExDoc (checks for {:ex_doc in mix.exs)
3. Runs mix docs --warnings-as-errors to validate documentation
4. Blocks the commit (via JSON permissionDecision: “deny”) if validation fails
5. Allows the commit to proceed if validation passes

Note: Skips if project has a precommit alias (defers to precommit plugin)

Concurrent Execution Protection

When multiple plugins run in parallel during commits, the ExDoc plugin uses atomic directory-based locking to prevent race conditions:

• Serialized execution - Only one mix docs process runs at a time per project
• Automatic locking - Uses atomic mkdir to acquire an exclusive lock before generating documentation
• Cross-platform - Works on both macOS and Linux without requiring external dependencies
• Prevents conflicts - Eliminates “file already exists” errors when multiple hooks trigger simultaneously
• Lock directory location - Stored in /tmp with project-specific name (automatically cleaned up)
• Timeout handling - Waits up to 60 seconds for lock acquisition, prevents indefinite blocking

This is necessary because mix docs removes and recreates the doc/ directory, which would conflict if multiple instances ran concurrently.

Why Pre-Commit Only?

Unlike other plugins that provide post-edit feedback, the ExDoc plugin only validates at commit time because:

• Performance - mix docs regenerates entire documentation (10-30+ seconds), which would slow down every file edit
• Similar to Dialyzer - Follows the same pattern as the Dialyzer plugin, which also only runs pre-commit due to analysis time
• Quality gate - Ensures documentation quality without interrupting the development workflow
• Manual checking available - Developers can run mix docs manually anytime for immediate feedback

Usage

Once installed, the plugin automatically validates documentation before commits:

# Make changes to your code
# Edit lib/my_module.ex - add functions with @doc

# Attempt to commit
git commit -m "Add new feature"

# If documentation issues found:
# ❌ Commit is BLOCKED
# Error output shows documentation warnings/errors

# Fix the documentation issues
# Edit documentation to resolve issues

# Try commit again
git commit -m "Add new feature"

# If documentation is valid:
# ✅ Commit proceeds normally

Detected Issues

The plugin catches common documentation problems:

Undefined References

@doc """
This function calls `NonExistent.function/1`  # ⚠️ Warning: undefined reference
"""
def my_function do
  # ...
end

Broken File Links

@moduledoc """
See [guide](guides/missing.md) for details  # ⚠️ Warning: file doesn't exist
"""

Invalid Configuration

# In mix.exs
docs: [
  main: "NonExistentPage"  # ⚠️ Warning: main page not found
]

Configuration

The plugin works with your existing ExDoc configuration in mix.exs:

def project do
  [
    # ... other config
    docs: [
      main: "readme",
      extras: ["README.md", "CHANGELOG.md"],
      source_url: "https://github.com/user/repo",

      # Optional: Suppress specific warnings
      skip_undefined_reference_warnings_on: [
        "CHANGELOG.md",
        "DeprecatedModule"
      ]
    ]
  ]
end

Requirements

• ExDoc must be in your project dependencies ({:ex_doc in mix.exs)
• Mix project with mix.exs file
• Git repository (validation only runs on git commit)
• Timeout: 45 seconds (sufficient for most projects; increase if extensive documentation takes longer)

Disabling the Plugin

If you need to commit without documentation validation temporarily:

# Uninstall the plugin
/plugin uninstall ex_doc@elixir

# 

...(truncated)

## Source

[View on GitHub](https://github.com/bradleygolden/claude-marketplace-elixir)