edoc: Print a helpful message if reading source file fails

See also https://bugs.erlang.org/browse/ERL-841.

1 files changed, 14 insertions, 3 deletions

diff --git a/lib/edoc/src/edoc.erl b/lib/edoc/src/edoc.erl
index b641118c5d..e9d62d3283 100644
--- a/lib/edoc/src/edoc.erl
+++ b/lib/edoc/src/edoc.erl
@@ -578,7 +578,7 @@ read_source(Name, Opts0) ->
     Opts = expand_opts(Opts0),
     case read_source_1(Name, Opts) of
 	{ok, Forms} ->
-	    check_forms(Forms, Name),
+	    check_forms(Forms, Name, Opts),
 	    Forms;
 	{error, R} ->
 	    edoc_report:error({"error reading file '~ts'.",
@@ -692,13 +692,19 @@ fll([T | L], LastLine, Ts) ->
 fll(L, _LastLine, Ts) ->
     lists:reverse(L, Ts).
 
-check_forms(Fs, Name) ->
+check_forms(Fs, Name, Opts) ->
     Fun = fun (F) ->
 	     case erl_syntax:type(F) of
 		 error_marker ->
 		     case erl_syntax:error_marker_info(F) of
 			 {L, M, D} ->
-			     edoc_report:error(L, Name, {format_error, M, D});
+                             edoc_report:error(L, Name, {format_error, M, D}),
+                             case proplists:get_bool(preprocess, Opts) of
+                                 true ->
+                                     ok;
+                                 false ->
+                                     helpful_message(Name)
+                             end;
 			 Other ->
 			     edoc_report:report(Name, "unknown error in "
                                                 "source code: ~w.", [Other])
@@ -710,6 +716,11 @@ check_forms(Fs, Name) ->
 	  end,
     lists:foreach(Fun, Fs).
 
+helpful_message(Name) ->
+    Ms = ["If the error is caused by too exotic macro",
+          "definitions or uses of macros, adding option",
+          "{preprocess, true} can help. See also edoc(3)."],
+    lists:foreach(fun(M) -> edoc_report:report(Name, M, []) end, Ms).
 
 %% @spec get_doc(File::filename()) -> {ModuleName, edoc_module()}
 %% @equiv get_doc(File, [])