ERL-841: edoc syntax error

[OTP-Maintainer]

Original reporter: sdl.web@gmail.com
Affected version: OTP-21.2
Fixed in version: OTP-21.3
Component: edoc
Migrated from: https://bugs.erlang.org/browse/ERL-841

---

t.erl compiles without warnings or errors but edoc cannot handle it.

{noformat}
edoc:get_doc("/Users/leo/t.erl", []).
/Users/leo/t.erl: at line 7: syntax error before: '.'
** exception exit: error
     in function  edoc:'-check_forms/2-fun-0-'/2 (edoc.erl, line 706)
     in call from lists:foreach/2 (lists.erl, line 1338)
     in call from edoc:read_source/2 (edoc.erl, line 581)
     in call from edoc_extract:source/3 (edoc_extract.erl, line 57)
{noformat}

[OTP-Maintainer]

hasse said:

Try adding the option {preprocess, true}.

Best regards,

Hans Bolinder, Erlang/OTP team, Eriicsson

[OTP-Maintainer]

sdl.web@gmail.com said:

Thanks a lot. That fixes the issue. BTW, should that option default to true?

[OTP-Maintainer]

starbelly said:

I think it should default to true or you should get a better error message when edoc fails (i.e., "Complex definitions and/or macros have been detected in your source files, please add preprocessor true")  I believe it does not default to this as it is slower. I've seen a number of people get perplexed when running into this issue. 

[OTP-Maintainer]

hasse said:

A nicely formulated message as the one Bryan suggests requires some
analysis as the Erlang parser makes no attempt to pinpoint the cause
of a syntax error.

It's easy to add a line to the report, perhaps something like:

{code}
f.erl: at line 7: syntax error before: '.'
f.erl: at line 7: If the error is caused by a macro, adding option {preprocess, true} can help.
{code}

[OTP-Maintainer]

starbelly said:

I can do a PR on this if desired. 

[OTP-Maintainer]

richardc said:

It would be practically impossible to separate ordinary syntax errors like a missing comma from an error due to a weird macro.
You also don't want to set {preprocess,true} by default, because then you need to ensure that you feed all the correct include paths to edoc, or it will fail because of missing header files instead.
I like the suggestion by Hans to add an extra line reminding the user about the existence of the preprocess option, but it should preferably also say something about that it's best to avoid syntactically unbalanced constructs in macros to begin with.

[OTP-Maintainer]

starbelly said:

Oh yeah, definitely don't want to try and diagnose what wrong just that something went wrong, it may be because of X, and very much agree with the last bit "avoid syntactically unbalanced constructs in macros to begin with"

[OTP-Maintainer]

hasse said:

One way of trying to diagnose is to run with the \{preprocess, true} option...

More seriously, a patch based on maint along the lines of Richard's
comment would probably be accepted.

[OTP-Maintainer]

hasse said:

Please comment upon https://github.com/erlang/otp/pull/2150.

[OTP-Maintainer]

hasse said:

Merged commit aa1135ccc2354841c00b40da5f7260dc299b7bf3 into erlang:maint.