File 6745-erl_docgen-Include-title-metadata-in-chunk... of Package erlang

Overview Repositories Revisions Requests Users Attributes Meta

File 6745-erl_docgen-Include-title-metadata-in-chunks.patch of Package erlang (Revision edad8a0fdc21acfdb5dbfeb4b029dec5)

Currently displaying revision edad8a0fdc21acfdb5dbfeb4b029dec5 , Show latest

From a0d78640fe44d993f289062e9fd1779f615ed66f Mon Sep 17 00:00:00 2001
From: Lukas Larsson <lukas@erlang.org>
Date: Fri, 15 Sep 2023 13:02:10 +0200
Subject: [PATCH 5/7] erl_docgen: Include title metadata in chunks

If the functions/types are documented under a title
then include that title in the metadata of the
functions/types.
---
 lib/erl_docgen/src/docgen_xml_to_chunk.erl | 179 ++++++++++++---------
 1 file changed, 103 insertions(+), 76 deletions(-)

diff --git a/lib/erl_docgen/src/docgen_xml_to_chunk.erl b/lib/erl_docgen/src/docgen_xml_to_chunk.erl
index 195ce7fdd2..32c500453b 100644
--- a/lib/erl_docgen/src/docgen_xml_to_chunk.erl
+++ b/lib/erl_docgen/src/docgen_xml_to_chunk.erl
@@ -367,12 +367,25 @@ transform([{pre,Attr,Content}|T],Acc) ->
 
 %% transform <funcs> with <func> as children
 transform([{funcs,_Attr,Content}|T],Acc) ->
-    Fns = {functions,[],transform_funcs(Content, [])},
+    FnAttr =
+        case lists:keyfind(fsdescription, 1, Content) of
+            false -> [];
+            {fsdescription, _, FSDescr} ->
+                {_, _, Title} = lists:keyfind(h1, 1, FSDescr),
+                [{title, unicode:characters_to_binary(Title)}]
+        end,
+    Fns = {functions, FnAttr, transform_funcs(Content, [])},
     transform(T,[Fns|Acc]);
 %% transform <datatypes> with <datatype> as children
 transform([{datatypes,_Attr,Content}|T],Acc) ->
     Dts = transform(Content, []),
-    transform(T,[{datatypes,[],Dts}|Acc]);
+    DtAttr =
+        case lists:keyfind(datatype_title, 1, Content) of
+            false -> [];
+            {datatype_title, _, Title} ->
+                [{title,unicode:characters_to_binary(Title)}]
+        end,
+    transform(T,[{datatypes,DtAttr,Dts}|Acc]);
 transform([{datatype,_Attr,Content}|T],Acc) ->
     transform(T,transform_datatype(Content, []) ++ Acc);
 %% Ignore <datatype_title>
@@ -713,83 +726,97 @@ to_chunk(Dom, Source, Module, AST) ->
 
     Anno = erl_anno:set_file(atom_to_list(Module)++".erl",erl_anno:new(0)),
 
-    Types = lists:flatten([Types || {datatypes,[],Types} <- Mcontent]),
-
     TypeEntries =
-        lists:map(
-          fun({datatype,Attr,Descr}) ->
-                  {function, TypeName} = func_to_atom(proplists:get_value(name,Attr)),
-                  TypeArity = case proplists:get_value(n_vars,Attr) of
-                                  undefined ->
-                                      find_type_arity(TypeName, TypeMap);
-                                  Arity ->
-                                      list_to_integer(Arity)
-                              end,
-                  TypeArgs = lists:join(",",[lists:concat(["Arg",I]) || I <- lists:seq(1,TypeArity)]),
-                  {TypeSignature, MetaSig} =
-                      case proplists:get_value(signature,Attr) of
-                          undefined ->
-                              PlaceholderSig =
-                                  iolist_to_binary(
-                                    io_lib:format("-type ~p(~s) :: term().",
-                                                  [TypeName,TypeArgs])),
-                              {[PlaceholderSig],
-                               case maps:get({TypeName, TypeArity}, TypeMap, undefined) of
-                                   undefined ->
-                                       #{};
-                                   Sig ->
-                                       #{ signature => [Sig] }
-                               end};
-                          Signature ->
-                              {Signature, #{}}
-                      end,
-
-                  MetaDepr
-                      = case apply(otp_internal,obsolete_type,[Module, TypeName, TypeArity]) of
-                            %% apply/3 in order to silence dialyzer
-                            {deprecated, Text} ->
-                                MetaSig#{ deprecated =>
-                                              unicode:characters_to_binary(
-                                                erl_lint:format_error({deprecated_type,{Module,TypeName,TypeArity}, Text})) };
-                            {deprecated, Replacement, Rel} ->
-                                MetaSig#{ deprecated =>
-                                              unicode:characters_to_binary(
-                                                erl_lint:format_error({deprecated_type,{Module,TypeName,TypeArity}, Replacement, Rel})) };
-                            {removed, _Text} ->
-                                %% Just skip
-                                MetaSig;
-                            no ->
-                                MetaSig
-                        end,
-
-                  docs_v1_entry(type, Anno, TypeName, TypeArity, TypeSignature, MetaDepr, Descr)
-          end, Types),
-
-    Functions = lists:flatten([Functions || {functions,[],Functions} <- Mcontent]),
+        lists:flatmap(
+          fun({datatypes, DTsAttr, Types}) ->
+                  TitleMD = case proplists:get_value(title, DTsAttr) of
+                                undefined -> #{};
+                                Title ->
+                                    #{ title => Title }
+                            end,
+                  lists:map(
+                    fun({datatype,Attr,Descr}) ->
+                            {function, TypeName} = func_to_atom(proplists:get_value(name,Attr)),
+                            TypeArity = case proplists:get_value(n_vars,Attr) of
+                                            undefined ->
+                                                find_type_arity(TypeName, TypeMap);
+                                            Arity ->
+                                                list_to_integer(Arity)
+                                        end,
+                            TypeArgs = lists:join(",",[lists:concat(["Arg",I]) || I <- lists:seq(1,TypeArity)]),
+                            {TypeSignature, MetaSig} =
+                                case proplists:get_value(signature,Attr) of
+                                    undefined ->
+                                        PlaceholderSig =
+                                            iolist_to_binary(
+                                              io_lib:format("-type ~p(~s) :: term().",
+                                                            [TypeName,TypeArgs])),
+                                        {[PlaceholderSig],
+                                         case maps:get({TypeName, TypeArity}, TypeMap, undefined) of
+                                             undefined ->
+                                                 TitleMD#{};
+                                             Sig ->
+                                                 TitleMD#{ signature => [Sig] }
+                                         end};
+                                    Signature ->
+                                        {Signature, TitleMD#{}}
+                                end,
+
+                            MetaDepr
+                                = case apply(otp_internal,obsolete_type,[Module, TypeName, TypeArity]) of
+                                      %% apply/3 in order to silence dialyzer
+                                      {deprecated, Text} ->
+                                          MetaSig#{ deprecated =>
+                                                        unicode:characters_to_binary(
+                                                          erl_lint:format_error({deprecated_type,{Module,TypeName,TypeArity}, Text})) };
+                                      {deprecated, Replacement, Rel} ->
+                                          MetaSig#{ deprecated =>
+                                                        unicode:characters_to_binary(
+                                                          erl_lint:format_error({deprecated_type,{Module,TypeName,TypeArity}, Replacement, Rel})) };
+                                      {removed, _Text} ->
+                                          %% Just skip
+                                          MetaSig;
+                                      no ->
+                                          MetaSig
+                                  end,
+
+                            docs_v1_entry(type, Anno, TypeName, TypeArity, TypeSignature, MetaDepr, Descr)
+                    end, Types);
+             (_) -> []
+          end, Mcontent),
 
     FuncEntrys =
-        lists:map(
-          fun({function,Attr,Fdoc}) ->
-                  {Type, Name} = func_to_atom(proplists:get_value(name,Attr)),
-                  Arity = proplists:get_value(arity,Attr),
-                  Signature = proplists:get_value(signature,Attr),
-                  FMeta = proplists:get_value(meta,Attr),
-                  MetaWSpec = add_spec(AST,FMeta),
-                  MetaDepr
-                      = case apply(otp_internal,obsolete,[Module, Name, Arity]) of
-                            %% apply/3 in order to silence dialyzer
-                            {deprecated, Text} ->
-                                MetaWSpec#{ deprecated =>
-                                                unicode:characters_to_binary(
-                                                  erl_lint:format_error({deprecated,{Module,Name,Arity}, Text})) };
-                            {deprecated, Replacement, Rel} ->
-                                MetaWSpec#{ deprecated =>
-                                                unicode:characters_to_binary(
-                                                  erl_lint:format_error({deprecated,{Module,Name,Arity}, Replacement, Rel})) };
-                            _ -> MetaWSpec
-                        end,
-                  docs_v1_entry(Type, Anno, Name, Arity, Signature, MetaDepr, Fdoc)
-          end, Functions),
+        lists:flatmap(
+          fun({functions, FsAttr, Functions}) ->
+                  TitleMD = case proplists:get_value(title, FsAttr) of
+                                undefined -> #{};
+                                Title ->
+                                    #{ title => Title }
+                            end,
+                  lists:map(
+                    fun({function,Attr,Fdoc}) ->
+                            {Type, Name} = func_to_atom(proplists:get_value(name,Attr)),
+                            Arity = proplists:get_value(arity,Attr),
+                            Signature = proplists:get_value(signature,Attr),
+                            FMeta = maps:merge(proplists:get_value(meta,Attr),TitleMD),
+                            MetaWSpec = add_spec(AST,FMeta),
+                            MetaDepr
+                                = case apply(otp_internal,obsolete,[Module, Name, Arity]) of
+                                      %% apply/3 in order to silence dialyzer
+                                      {deprecated, Text} ->
+                                          MetaWSpec#{ deprecated =>
+                                                          unicode:characters_to_binary(
+                                                            erl_lint:format_error({deprecated,{Module,Name,Arity}, Text})) };
+                                      {deprecated, Replacement, Rel} ->
+                                          MetaWSpec#{ deprecated =>
+                                                          unicode:characters_to_binary(
+                                                            erl_lint:format_error({deprecated,{Module,Name,Arity}, Replacement, Rel})) };
+                                      _ -> MetaWSpec
+                                  end,
+                            docs_v1_entry(Type, Anno, Name, Arity, Signature, MetaDepr, Fdoc)
+                    end, Functions);
+             (_) -> []
+          end, Mcontent),
 
     docs_v1(ModuleDocs, Anno, TypeMeta, FuncEntrys ++ TypeEntries).
 
-- 
2.35.3

Places

File 6745-erl_docgen-Include-title-metadata-in-chunks.patch of Package erlang (Revision edad8a0fdc21acfdb5dbfeb4b029dec5)

Places