rebar3_ex_doc plugin fails when .erl file contains function named `record`

max-au commented 2 years ago

Discovered trying to ex_doc erlperf: https://github.com/max-au/erlperf/blob/master/src/erlperf.erl#L137

Although minimal repro could be just

-module(test).
-export([record/1]).

-spec record(module()) -> [[{module(), atom()}]].
record(Mod) -> [[{Mod, ok}]].

Output is:

rebar3 hex publish docs
===> Verifying dependencies...
<...>
===> Running ex_doc for erlperf
===> warning: internal inconsistency, please submit bug: "module" != "atom"
  src/test.erl:5: test.record/1

19:56:02.717 [error] Task #PID<0.129.0> started from #PID<0.116.0> terminating
** (MatchError) no match of right hand side value: []
    (ex_doc 0.28.3) lib/ex_doc/language/erlang.ex:558: ExDoc.Language.Erlang.pop/0
    (ex_doc 0.28.3) lib/ex_doc/language/erlang.ex:512: anonymous fn/2 in ExDoc.Language.Erlang.replace/3

Renaming record/1 into record1/1 makes the error go away.

starbelly commented 2 years ago

The issue is there is an exception in ex_doc that handles walking the ast for specs. Specifically here : https://github.com/elixir-lang/ex_doc/blob/935f2dac019d0bdcb470e68fc8b077e4e27bfe15/lib/ex_doc/language/erlang.ex#L463

A fix that I came up with is to check to see if the accumulator is empty :

 name in [:"::", :when, :%{}, :{}, :|, :->, :record] and acc != [] ->

But I'm not sure if that's appropriate or introduces other problems. Probably should open an issue on ex_doc.

Edit :

Note if you wanted to get docs published quickly without waiting on this to be resolved what you could do is :

mkdir _checkouts
clone rebar3_ex_doc to _checkouts
mix deps.get
Adjust the line of code in deps/ex_doc/lib/ex_doc/language/erlang.ex at line 463
mix deps.compile
mix escript.build
cd .. (back to your project)
rebar3 ex_doc

starbelly commented 1 year ago

Resolved via https://github.com/elixir-lang/ex_doc/pull/1576

jelly-beam / rebar3_ex_doc

rebar3_ex_doc plugin fails when .erl file contains function named `record` #26