Rebar3 ex_doc crashes on a backtick in a comment for native -doc projects - is my fix in the right place?

Questions / Help
, , , ,
1

Hi all :waving_hand:

While building HTML docs for a small Erlang lib of mine that’s documented 100% with native OTP 27+ attributes (-moduledoc / -doc, EEP-59 — zero @doc EDoc comments), rebar3 ex_doc kept aborting with:

edoc: error in doclet 'edoc_doclet_chunks': {'EXIT',error}.

Root cause (short version): rebar3 ex_doc runs EDoc before calling ex_doc, to generate doc chunks. EDoc parses every %% comment through its legacy “wiki” markup, where a backtick opens an inline-code span that must be closed by an apostrophe (`code'). A normal Markdown backtick (`code`) never gets that closing ', so the parser throws and the whole command aborts. The kicker: that EDoc step is vestigial for native-doc projects — ex_doc reads the docs straight from the BEAM’s EEP-48 Docs chunk, not from EDoc’s output. So a backtick in an ordinary comment crashes doc generation for code that doesn’t use EDoc at all. (Same issue as jelly-beam/rebar3_ex_doc#123.)

My PR — #129: graceful degradation. EDoc still runs, but if it fails and the app’s beams already carry populated native docs, the plugin logs the real error and continues to ex_doc instead of aborting. The happy path is unchanged, there’s no default flip, and legacy @doc projects keep the original abort behavior (they carry no native Docs chunk, so nothing changes for them).

Where I’d genuinely love opinions:

  1. Is a plugin-level fix even the right call here — or should this be solved differently (a config option to skip EDoc when native docs are present, or just left to the user)? I want to make sure I’m not patching this in the wrong layer.

  2. I came to the conclusion that #129 only makes the plugin coexist with the bug — the real fix is upstream in OTP:

    • edoc_wiki shouldn’t throw on an unterminated backtick in comment text; it should degrade to literal text. A comment should never be able to crash doc generation.
    • edoc_doclet_chunks should surface the real error instead of swallowing it into {'EXIT', error} — that’s erlang/otp#5778, open since 2022.

    Do these feel worth turning into PRs against erlang/otp? If anyone has context on EDoc’s internals, I’d love a sanity check on the approach before I open them.

I searched the forums before posting — the closest existing threads are the rebar3_ex_doc plugin thread (same swallowed {'EXIT',error} symptom, but a different trigger) and the OTP 27.0 release thread (which covers ExDoc reading EEP-48 docs straight from the BEAM). Neither covers this backtick-in-a-comment failure, so I’m opening a fresh thread.

Thanks for reading! :folded_hands: