Fix docs to handle Erlang docs when they conform to EEP48

This is valid from OTP 23 onwards where we can use code:get_doc to find the doc which can handle chunks in beam files and in separate chunk files. The formatting is still primitive but we step through long texts in a simple way.
lfe · Oct 8, 2020 · df81d9c · df81d9c
1 parent da8f1d2
commit df81d9c
Show file tree

Hide file tree

Showing 8 changed files with 191 additions and 100 deletions.
diff --git a/doc/lfe.txt b/doc/lfe.txt
@@ -117,7 +117,7 @@ BUILT-IN SHELL COMMANDS
        (reset-environment)
 
        Resets the environment to its initial state.  This will clear all vari‐
-       ables, functions an macros that have been set.
+       ables, functions and macros that have been set.
 
        (run File)
 
@@ -165,7 +165,7 @@ BUILT-IN SHELL VARIABLES
 
        *, **, ***
 
-       The values of the previous 3 expressions.
+       The values of the previous three expressions.
 
        -
 
@@ -257,4 +257,4 @@ AUTHORS
 
 
 
-                                   2008-2019                            lfe(1)
+                                   2008-2020                            lfe(1)
diff --git a/doc/man/lfe.1 b/doc/man/lfe.1
@@ -1,6 +1,6 @@
 .\" Automatically generated by Pandoc 1.19.2.1
 .\"
-.TH "lfe" "1" "2008\-2019" "" ""
+.TH "lfe" "1" "2008\-2020" "" ""
 .hy
 .SH NAME
 .PP
@@ -122,7 +122,7 @@ The cannot be redefined.
 \f[B](reset\-environment)\f[]
 .PP
 Resets the environment to its initial state.
-This will clear all variables, functions an macros that have been set.
+This will clear all variables, functions and macros that have been set.
 .PP
 \f[B](run File)\f[]
 .PP
@@ -171,7 +171,7 @@ The three previous expressions input.
 .PP
 \f[B]\f[C]*\f[], \f[C]**\f[], \f[C]***\f[]\f[]
 .PP
-The values of the previous 3 expressions.
+The values of the previous three expressions.
 .PP
 \f[B]\f[C]\-\f[]\f[]
 .PP

diff --git a/doc/src/lfe.1.md b/doc/src/lfe.1.md
@@ -1,6 +1,6 @@
 % lfe(1)
 % Robert Virding
-% 2008-2019
+% 2008-2020
 
 
 # NAME
@@ -122,7 +122,7 @@ top-level in shell input. The cannot be redefined.
 **(reset-environment)**
 
 Resets the environment to its initial state. This will clear all
-variables, functions an macros that have been set.
+variables, functions and macros that have been set.
 
 **(run File)**
 
@@ -176,7 +176,7 @@ The three previous expressions input.
 
 **``*``, ``**``, ``***``**
 
-The values of the previous 3 expressions.
+The values of the previous three expressions.
 
 **``-``**
 
@@ -264,9 +264,8 @@ The name of the script file as a string.
 
 **script-args**
 
-A list of the arguments to the script as strings. If
-no arguments have been given then this will be an
-empty list.
+A list of the arguments to the script as strings. If no arguments have
+been given then this will be an empty list.
 
 Note that if there are any string expressions to be evaluated then
 these must come before the name of the script file and its

diff --git a/get_comp_opts.escript b/get_comp_opts.escript
@@ -49,7 +49,8 @@ comp_opts(Version) ->
                                      {"20","NEW_BOOL_GUARD"},
                                      {"20","HAS_FLOOR"},
                                      {"20","HAS_CEIL"},
-                                     {"21","NEW_STACKTRACE"}]).
+                                     {"21","NEW_STACKTRACE"},
+                                     {"23","EEP48"}]).
 
 append_copts(Version, [{Ver,Opt}|Opts]) ->
     Rest = append_copts(Version, Opts),

diff --git a/rebar.config.script b/rebar.config.script
@@ -69,7 +69,8 @@ Copts = Copts0 ++ AppendCopts(Version,
                                {"20",'NEW_BOOL_GUARD'},
                                {"20",'HAS_FLOOR'},
                                {"20",'HAS_CEIL'},
-                               {"21",'NEW_STACKTRACE'}],
+                               {"21",'NEW_STACKTRACE'},
+                               {"23",'EEP48'}],
                               AppendCopts),
 
 %% Ensure they are in erl_opts.

diff --git a/src/lfe_docs.erl b/src/lfe_docs.erl
@@ -41,8 +41,6 @@
 
 -export([get_module_docs/1]).
 
--define(CURR_DOC_VERSION, {1,0,0}).
-
 -include("lfe_docs.hrl").
 
 %% Internal lfe_doc records.
@@ -161,8 +159,8 @@ collect_mac_metas(Metas, Mac) ->
 
 generate_funcs(#docs{module=#module{fexps=Fexps},funcs=Funcs}) ->
     Fdoc = fun (#function{name=Name,arity=Arity,anno=Anno,docs=Docs}=F) ->
-		   Sig = generate_sig(F),
-		   docs_v1_entry(function, Name, Arity, Anno, [Sig], Docs, #{})
+                   Sig = generate_sig(F),
+                   docs_v1_entry(function, Name, Arity, Anno, [Sig], Docs, #{})
            end,
     [ Fdoc(F) || F <- Funcs, exported_func(F, Fexps)].
 
@@ -173,8 +171,8 @@ exported_func(#function{name=N,arity=A}, Fexps) ->
 
 generate_macros(#docs{module=#module{mexps=Mexps},macs=Macros}) ->
     Mdoc = fun (#macro{name=Name,arity=Arity,anno=Anno,docs=Docs}=M) ->
-		   Sig = generate_sig(M),
-		   docs_v1_entry(macro, Name, Arity, Anno, [Sig], Docs, #{})
+                   Sig = generate_sig(M),
+                   docs_v1_entry(macro, Name, Arity, Anno, [Sig], Docs, #{})
            end,
     [ Mdoc(M) || M <- Macros, exported_macro(M, Mexps) ].
 
@@ -204,39 +202,48 @@ docs_v1(Anno, ModDoc, Metadata, Docs) ->
     Doc = #{<<"en">> => iolist_to_binary(ModDoc)},
     Meta = maps:merge(Metadata, #{otp_doc_vsn => ?CURR_DOC_VERSION}),
     #docs_v1{anno=Anno,
-	     beam_language=lfe,
-	     format= <<"text/application">>,
-	     module_doc=Doc,
-	     metadata=Meta,
-	     docs=Docs}.
+             beam_language=lfe,
+             format= ?LFE_FORMAT,
+             module_doc=Doc,
+             metadata=Meta,
+             docs=Docs}.
 
 docs_v1_entry(Kind, Name, Arity, Anno, Sig, DocContent, Meta) ->
     %% Doc = case DocContent of
-    %% 	      [] -> #{};
-    %% 	      _ -> #{<<"en">> => iolist_to_binary(DocContent)}
-    %% 	  end,
+    %%        [] -> #{};
+    %%        _ -> #{<<"en">> => iolist_to_binary(DocContent)}
+    %%    end,
     Doc = #{<<"en">> => iolist_to_binary(DocContent)},
     {{Kind,Name,Arity}, Anno, Sig, Doc, Meta}.
 
-%% get_module_docs(Module | Binary) -> {ok,Chunk} | {error,What}.
+%% get_module_doc(Module | Binary) -> {ok,Chunk} | {error,What}.
+%%  Get the module doc chunk. If EEP48 is defined we can use the code
+%%  module to do mosst of the work.
+
+-ifdef(EEP48).
+
+get_module_docs(Mod) when is_atom(Mod) ->
+    code:get_doc(Mod);
+get_module_docs(Bin) when is_binary(Bin) ->
+    get_module_chunk(Bin).
+
+-else.
 
 get_module_docs(Mod) when is_atom(Mod) ->
-    case code:get_doc(Mod) of
-	{ok,Doc} -> {ok,Doc};
-	{error,_} -> {error,module}
+    case code:get_object_code(Mod) of
+        {Mod,Bin,_} ->
+            get_module_chunk(Bin);
+        error -> {error,non_existing}           %Could not find the module
     end;
-%% get_module_docs(Mod) when is_atom(Mod) ->
-%%     case code:get_object_code(Mod) of
-%%         {Mod,Bin,_} ->
-%%             get_module_chunk(Bin);
-%%         error -> {error,module}                 %Could not find the module
-%%     end;
 get_module_docs(Bin) when is_binary(Bin) ->
     get_module_chunk(Bin).
 
+-endif.
+
 get_module_chunk(Bin) ->
     case beam_lib:chunks(Bin, ["Docs"], []) of
         {ok,{_,[{"Docs",Chunk}]}} ->
             {ok,binary_to_term(Chunk)};
-        _ -> {error,docs}                       %Could not find the docs chunk
+        {error,beam_lib,Error} ->
+            {error,Error}
     end.
diff --git a/src/lfe_docs.hrl b/src/lfe_docs.hrl
@@ -33,6 +33,11 @@
 %%     }]} when DocLanguage :: binary(),
 %%              DocValue :: binary() | term()
 
+-define(NATIVE_FORMAT,<<"application/erlang+html">>).
+-define(LFE_FORMAT,   <<"text/markdown">>).
+
+-define(CURR_DOC_VERSION, {1,0,0}).
+
 %% The Docs v1 record.
 -record(docs_v1, {anno,
                   beam_language,