File 4433-stdlib-Update-shell_docs-normalize-to-alwa... of Package erlang

Overview Repositories Revisions Requests Users Attributes Meta

File 4433-stdlib-Update-shell_docs-normalize-to-always-have-bl.patch of Package erlang

From a8f592d105f4ef9d2b240cecc49381c0b4566731 Mon Sep 17 00:00:00 2001
From: Lukas Larsson <lukas@erlang.org>
Date: Wed, 6 Dec 2023 13:28:47 +0100
Subject: [PATCH 3/4] stdlib: Update shell_docs:normalize to always have blocks
 at top level

This change makes ExDoc rendering look nicer for edoc content.
---
 lib/edoc/src/edoc_layout_chunks.erl |  4 +++-
 lib/edoc/test/eep48_SUITE.erl       | 19 +++++++++++++++----
 lib/stdlib/src/shell_docs.erl       | 23 ++++++++++++++++++++++-
 3 files changed, 40 insertions(+), 6 deletions(-)

diff --git a/lib/edoc/src/edoc_layout_chunks.erl b/lib/edoc/src/edoc_layout_chunks.erl
index fd397d12be..69e377ca9b 100644
--- a/lib/edoc/src/edoc_layout_chunks.erl
+++ b/lib/edoc/src/edoc_layout_chunks.erl
@@ -479,7 +479,9 @@ xpath_to_text(XPath, Doc, Opts) ->
 	[] -> <<>>;
 	[#xmlAttribute{} = Attr] ->
 	    {_ , Value} = format_attribute(Attr),
-	    hd(shell_docs:normalize([Value]));
+            case shell_docs:normalize([Value]) of
+                [{p,[],[Normal]}] -> Normal
+            end;
 	[#xmlElement{}] = Elements ->
 	    xmerl_to_binary(Elements, Opts);
 	[_|_] ->
diff --git a/lib/edoc/test/eep48_SUITE.erl b/lib/edoc/test/eep48_SUITE.erl
index e56e88e93e..1db3fb9522 100644
--- a/lib/edoc/test/eep48_SUITE.erl
+++ b/lib/edoc/test/eep48_SUITE.erl
@@ -516,10 +516,21 @@ lookup_entry(Kind, Function, Arity, Docs) ->
 get_metadata({_, _, _, _, Metadata}) -> Metadata.
 
 get_doc_link(KNA, Docs) ->
-    [Link] = [ Node || {a, _, _} = Node <- get_doc(KNA, Docs) ],
-    {a, Attrs, _} = Link,
-    <<"https://erlang.org/doc/link/", ShortRel/bytes>> = fetch(rel, Attrs),
-    {ShortRel, fetch(href, Attrs)}.
+    D = get_doc(KNA, Docs),
+    case lists:foldl(fun F({a, _, _} = E, Acc) ->
+                        [E | Acc];
+                    F({_E, _, Es}, Acc) when is_list(Es) ->
+                        lists:foldl(F, Acc, Es);
+                    F(_, Acc) ->
+                        Acc
+                end, [], D) of
+        [{a, Attrs, _}] ->
+            <<"https://erlang.org/doc/link/", ShortRel/bytes>> = fetch(rel, Attrs),
+            {ShortRel, fetch(href, Attrs)};
+        _Else ->
+            ct:log("Could not find link in ~p",[D]),
+            ct:fail("Did not find link in docs")
+    end.
 
 get_anno(Kind, Name, Arity, Docs) ->
     {_, Anno, _, _, _} = lookup_entry(Kind, Name, Arity, Docs),
diff --git a/lib/stdlib/src/shell_docs.erl b/lib/stdlib/src/shell_docs.erl
index 1962c97b07..1b51bc1a62 100644
--- a/lib/stdlib/src/shell_docs.erl
+++ b/lib/stdlib/src/shell_docs.erl
@@ -195,7 +195,8 @@ validate_docs([],_) ->
       NormalizedDocs :: chunk_elements().
 normalize(Docs) ->
     Trimmed = normalize_trim(Docs,true),
-    normalize_space(Trimmed).
+    Space = normalize_space(Trimmed),
+    normalize_paragraph(Space).
 
 normalize_trim(Bin,true) when is_binary(Bin) ->
     %% Remove any whitespace (except \n) before or after a newline
@@ -341,6 +342,26 @@ trim_last([{Elem,Attr,Content} = Tag|T],What) ->
 trim_last([],_What) ->
     {[],false}.
 
+%% Any non-block elements at top level are wrapped in a p so that tools
+%% don't have to deal with that.
+normalize_paragraph([{Tag,_,_} = Block | T]) when ?IS_BLOCK(Tag) ->
+    [Block | normalize_paragraph(T)];
+normalize_paragraph([{_,_,[]} = NoContent | T]) ->
+    %% If an inline tag has no content we don't wrap it in a <p>. This is
+    %% aimed at fixing <a id=""/> tags at top-level.
+    [NoContent | normalize_paragraph(T)];
+normalize_paragraph([]) ->
+    [];
+normalize_paragraph(Elems) ->
+    case lists:splitwith(
+           fun(E) ->
+                   is_binary(E) orelse
+                     (?IS_INLINE(element(1, E)) andalso element(3, E) =/= [])
+           end, Elems) of
+        {NotP, P} ->
+            [{p,[],NotP} | normalize_paragraph(P)]
+    end.
+
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 %% API function for dealing with the function documentation
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-- 
2.35.3

Places

File 4433-stdlib-Update-shell_docs-normalize-to-always-have-bl.patch of Package erlang

Places