# `UsageRules.Validator`
[🔗](https://github.com/ash-project/usage_rules/blob/v1.3.1/lib/usage_rules/validator.ex#L5)

Validates documentation references in usage-rules-managed markdown files
by driving ex_doc's own autolink pipeline over them.

This is the engine behind `mix usage_rules.validate`. Each file is parsed
and autolinked exactly like an extra page in a docs build — through ex_doc's
extras builder and its formatter autolink pass — and the warnings are
ex_doc's own, printed with file/line information: the same warnings you
would get from a HexDocs build over the same content.

## What ex_doc checks

  * function references with arity in inline code spans
    (`Module.function/arity`, `:erlang.function/arity`) — including
    `@doc false` / `@moduledoc false` targets, which are reported as
    "hidden or private"
  * hidden modules mentioned in inline code spans
  * explicit reference links in backtick form: `` [`Mod`](`Mod`) `` and
    `` [`mix task`](`mix task`) ``
  * relative file links between the validated files (links to files that
    are not part of the validated set do not resolve and are reported)

## What ex_doc does not check

ex_doc deliberately skips fenced code blocks when autolinking, and it
stays silent about plain code span mentions that never resolve, such as
`mix task` names and bare undefined module names — the same silence you
get inside moduledocs. Validation warnings are exactly a docs build's
warnings, nothing more and nothing less.

ex_doc must be compiled and available. When it is not, validation fails
with an actionable error (see `ensure_ex_doc!/1`).

# `ensure_ex_doc!`

```elixir
@spec ensure_ex_doc!((module() -> {:module, module()} | {:error, term()})) :: :ok
```

Ensures the ex_doc machinery is compiled and running, or fails with an
actionable error.

`validate/1` resolves references with ex_doc, so it must be compiled and
available. ex_doc is already a dev dependency of most Hex packages; when
it is missing, add it to your `mix.exs` and compile it.

The loader (defaults to `Code.ensure_loaded/1`) is injectable so tests can
exercise the failure path.

# `validate`

```elixir
@spec validate([Path.t()]) :: %{files: [Path.t()], warned?: boolean()}
```

Validates the given markdown files (paths on disk) with ex_doc's own
autolink pipeline.

ex_doc's warnings are printed to stderr as they are found, in ex_doc's own
format with file/line information. Returns:

    %{files: [path], warned?: boolean()}

`warned?` is true when ex_doc emitted at least one warning, which callers
should treat as validation failure.

---

*Consult [api-reference.md](api-reference.md) for complete listing*