Skip to content

docs: clear all ex_doc warnings - #70

Merged
Taure merged 1 commit into
masterfrom
fix/ex-doc-warnings
Aug 8, 2026
Merged

docs: clear all ex_doc warnings#70
Taure merged 1 commit into
masterfrom
fix/ex-doc-warnings

Conversation

@Taure

@Taure Taure commented Aug 8, 2026

Copy link
Copy Markdown
Contributor

rebar3 ex_doc emitted 123 warnings. Now it emits none.

122 of them: rebar_state:t/0

warning: spec references type "rebar_state:t/0" but it is undefined or private
  └─ (rebar3_nova) src/rebar3_nova_serve.erl:26

One per reference, across all 16 modules. Every provider spec names rebar_state:t():

-spec init(rebar_state:t()) -> {ok, rebar_state:t()}.

rebar3 is the host application, not a dependency, so its modules are absent from the doc build and ex_doc cannot resolve the type. That will not change - rebar3 ships as an escript with no ebin directory to point deps at. The specs are correct; the warning is unresolvable noise.

What I tried first

skip_code_autolink_to looked like the precise fix - suppress by type name. It does nothing here: the spec-autolink path never consults it, and rebar3_ex_doc reports it as unknown ex_doc option. Warnings stayed at 122.

The option that works is skip_undefined_reference_warnings_on, and two things about it are worth stating plainly:

  • It matches on module or file, not on the referenced type (ExDoc.Autolink.maybe_warn/4 tests config.id, config.module_id and the file path). So it cannot be narrowed to rebar_state:t/0 - the granularity does not exist.
  • All 16 modules is every module, so for module docs this is the whole warning class, not a targeted allowlist. I would rather say that than let the list imply otherwise.

What redeems it: extras are not covered. I verified that by pointing README.md at a non-existent file and confirming it still warned:

warning: documentation references file "does-not-exist.md" but it does not exist
  └─ README.md: (file)

So broken links in README.md and LICENSE keep surfacing - which for a plugin is where the docs actually live, main being readme.

The known wart: a newly added module will not be in the list and will start warning again. It is self-announcing, and the comment in rebar.config explains why the list exists.

The 123rd

README.md:2 had a stray ===== setext underline sitting under an ATX # heading. Removed.

Checks

ex_doc 0 warnings, fmt --check, xref, ct 28/28 all clean.

`rebar3 ex_doc` emitted 123 warnings.

122 of them were "spec references type rebar_state:t/0 but it is undefined
or private", one per reference across all 16 modules. Every provider spec
names rebar_state:t(), but rebar3 is the host application rather than a
dependency, so its modules are absent from the doc build and ex_doc cannot
resolve the type. It never will - rebar3 ships as an escript with no ebin
directory to point at - so the specs are correct and the warning is noise.

Suppressed with skip_undefined_reference_warnings_on. Two things worth
knowing about that option: it matches on module or file rather than on the
referenced type, so it cannot be narrowed to rebar_state:t() alone, and
listing all 16 modules is in practice the whole warning class for module
docs. Extras are unaffected - verified by pointing README.md at a
non-existent file, which still warned - so broken links in README.md and
LICENSE continue to surface, which is where the docs for a plugin actually
live.

The remaining warning was a stray setext underline left under an ATX
heading on README.md:2.

`rebar3 ex_doc` is now clean.
@Taure
Taure merged commit 83dc76b into master Aug 8, 2026
29 checks passed
@Taure
Taure deleted the fix/ex-doc-warnings branch August 8, 2026 11:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant