Explico

Explico runs Vale against @moduledoc, @doc, and @typedoc content and reports findings as Credo issues at their original source lines. It lets Elixir projects enforce their own prose policies through existing Credo workflows.

Requirements

To run documentation checks, install Vale and make vale available on PATH. Explico is tested with Vale 3.15.1.

If the vale executable is not found, Explico skips its check without affecting other configured Credo checks. Vale configuration errors or execution failures are reported as Credo issues.

Each consuming application owns its .vale.ini, Vale styles, terminology, and writing policy. Explico does not provide a default policy for consumers.

Installation

Add Explico beside Credo as a development dependency:

{:credo, "~> 1.7", only: [:dev, :test], runtime: false},
{:explico, "~> 0.1.1", only: [:dev, :test], runtime: false}

Credo configuration

Explico provides Explico.Check.Vale, which extracts all selected Elixir documentation and runs Vale once. Add it to your project's .credo.exs:

%{
  configs: [
    %{
      name: "explico",
      checks: %{
        extra: [
          {Explico.Check.Vale, []}
        ]
      }
    }
  ]
}

Expose project aliases that forward files and flags to Credo:

explico: "credo suggest --config-name explico --only Explico.Check.Vale",
"explico.diff": "credo diff --config-name explico --only Explico.Check.Vale"

Usage

Use Explico for documentation embedded in Elixir source files:

mix explico lib/my_app/accounts.ex
mix explico --strict lib/my_app/accounts.ex
mix explico.diff origin/main

Check standalone Markdown files directly with Vale:

vale README.md
vale docs/

Example output

Given a consumer Vale rule that flags vague language:

@doc """
Handles user authentication.
"""
def authenticate(credentials), do: Auth.authenticate(credentials)

Explico reports the finding through Credo:

Warnings - please take a look
┃
┃ [R] → [Docs.VagueBehavior] Describe the specific behavior instead of using 'Handles'.
┃       lib/my_app/accounts.ex:12 #(module)

Explico maps each finding back to its original documentation attribute.

How it works

Explico.Check.Vale receives selected source files from Credo. The check extracts @moduledoc, @doc, and @typedoc into temporary Markdown files. One Vale process checks the batch. Explico converts the results into Credo.Issue structs at the original Elixir lines.

Consumer Vale configuration defines the prose policy. Credo provides file selection and issue reporting; Explico connects them while preserving source locations.

License

Explico is available under the Apache License 2.0.