compute grouped docs summary in retriever

Author: lud

lib/ex_doc/formatter/epub/templates/module_template.eex

@@ -18,11 +18,11 @@
     <%= if summary != [] do %>
       <section id="summary" class="details-list">
         <h1 class="section-heading">Summary</h1>
-        <%= for {group, nodes} <- summary, do: H.summary_template(group.title, nodes) %>
+        <%= for group <- summary, do: H.summary_template(group.title, group.docs) %>
       </section>
     <% end %>
 
-    <%= for {group, nodes} <- summary, key = text_to_id(group.title) do %>
+    <%= for group <- summary, key = text_to_id(group.title) do %>
       <section id="<%= key %>" class="details-list">
         <h1 class="section-heading"><%=h to_string(group.title) %></h1>
         <%= if doc = group.rendered_doc do %>
@@ -31,7 +31,7 @@
           </div>
         <% end %>
         <div class="<%= key %>-list">
-          <%= for node <- nodes, do: H.detail_template(node, module) %>
+          <%= for node <- group.docs, do: H.detail_template(node, module) %>
         </div>
       </section>
     <% end %>

lib/ex_doc/formatter/html.ex

@@ -87,33 +87,32 @@ defmodule ExDoc.Formatter.HTML do
             language: language
           ] ++ base
 
-        docs =
-          for child_node <- node.docs do
-            id = id(node, child_node)
-
-            autolink_opts =
-              autolink_opts ++
-                [
-                  id: id,
-                  line: child_node.doc_line,
-                  file: child_node.doc_file,
-                  current_kfa: {child_node.type, child_node.name, child_node.arity}
-                ]
-
-            specs = Enum.map(child_node.specs, &language.autolink_spec(&1, autolink_opts))
-            child_node = %{child_node | specs: specs}
-            render_doc(child_node, language, autolink_opts, opts)
-          end
-
         docs_groups =
           for group <- node.docs_groups do
-            render_doc(group, language, autolink_opts, opts)
+            docs =
+              for child_node <- group.docs do
+                id = id(node, child_node)
+
+                autolink_opts =
+                  autolink_opts ++
+                    [
+                      id: id,
+                      line: child_node.doc_line,
+                      file: child_node.doc_file,
+                      current_kfa: {child_node.type, child_node.name, child_node.arity}
+                    ]
+
+                specs = Enum.map(child_node.specs, &language.autolink_spec(&1, autolink_opts))
+                child_node = %{child_node | specs: specs}
+                render_doc(child_node, language, autolink_opts, opts)
+              end
+
+            %{render_doc(group, language, autolink_opts, opts) | docs: docs}
           end
 
         %{
           render_doc(node, language, [{:id, node.id} | autolink_opts], opts)
-          | docs: docs,
-            docs_groups: docs_groups
+          | docs_groups: docs_groups
         }
       end,
       timeout: :infinity

lib/ex_doc/formatter/html/templates.ex

@@ -123,9 +123,9 @@ defmodule ExDoc.Formatter.HTML.Templates do
     {id, modules}
   end
 
-  defp sidebar_entries({group, nodes}) do
+  defp sidebar_entries(group) do
     nodes =
-      for node <- nodes do
+      for node <- group.docs do
         id =
           if "struct" in node.annotations do
             node.signature
@@ -153,17 +153,7 @@ defmodule ExDoc.Formatter.HTML.Templates do
     end)
   end
 
-  def module_summary(module_node) do
-    # TODO: Maybe it should be moved to retriever and it already returned grouped metadata
-
-    group_titles = Enum.map(module_node.docs_groups, & &1.title)
-    groups_index = Map.new(module_node.docs_groups, &{&1.title, &1})
-    docs_groups = ExDoc.GroupMatcher.group_by(group_titles, module_node.docs, & &1.group)
-
-    Enum.map(docs_groups, fn {group_title, nodes} ->
-      {Map.fetch!(groups_index, group_title), nodes}
-    end)
-  end
+  def module_summary(module_node), do: module_node.docs_groups
 
   defp favicon_path(%{favicon: nil}), do: nil
   defp favicon_path(%{favicon: favicon}), do: "assets/favicon#{Path.extname(favicon)}"

lib/ex_doc/formatter/html/templates/module_template.eex

@@ -39,11 +39,11 @@
       </a>
       <span class="text">Summary</span>
     </h1>
-    <%= for {group, nodes} <- summary, do: summary_template(group.title, nodes) %>
+    <%= for group <- summary, do: summary_template(group.title, group.docs) %>
   </section>
 <% end %>
 
-<%= for {group, nodes} <- summary, key = text_to_id(group.title) do %>
+<%= for group <- summary, key = text_to_id(group.title) do %>
   <section id="<%= key %>" class="details-list">
     <h1 class="section-heading">
       <a class="hover-link" href="#<%= key %>">
@@ -57,7 +57,7 @@
       </div>
     <% end %>
     <div class="<%= key %>-list">
-      <%= for node <- nodes, do: detail_template(node, module) %>
+      <%= for node <- group.docs, do: detail_template(node, module) %>
     </div>
   </section>
 <% end %>

lib/ex_doc/group_matcher.ex

@@ -14,23 +14,6 @@ defmodule ExDoc.GroupMatcher do
     Enum.find_index(groups, fn {k, _v} -> k == group end) || -1
   end
 
-  @doc """
-  Group the following entries while preserving the order in `groups`.
-  """
-  def group_by(groups, entries, by) do
-    entries = Enum.group_by(entries, by)
-
-    {groups, leftovers} =
-      Enum.flat_map_reduce(groups, entries, fn group, grouped_nodes ->
-        case Map.pop(grouped_nodes, group, []) do
-          {[], grouped_nodes} -> {[], grouped_nodes}
-          {entries, grouped_nodes} -> {[{group, entries}], grouped_nodes}
-        end
-      end)
-
-    groups ++ Enum.sort(leftovers)
-  end
-
   @doc """
   Finds a matching group for the given module name, id, and metadata.
   """

lib/ex_doc/nodes.ex

@@ -83,7 +83,7 @@ defmodule ExDoc.DocNode do
           source_doc: term() | nil,
           type: atom(),
           signature: String.t(),
-          specs: [ExDoc.Language.spec_ast()],
+          specs: [ExDoc.Language.spec_ast() | String.t()],
           annotations: [annotation()],
           group: String.t() | nil,
           doc_file: String.t(),
@@ -93,12 +93,13 @@ defmodule ExDoc.DocNode do
 end
 
 defmodule ExDoc.DocGroupNode do
-  defstruct title: nil, description: nil, doc: nil, rendered_doc: nil
+  defstruct title: nil, description: nil, doc: nil, rendered_doc: nil, docs: []
 
   @type t :: %__MODULE__{
           title: String.t() | atom(),
           description: String.t() | nil,
           doc: ExDoc.DocAST.t() | nil,
-          rendered_doc: String.t() | nil
+          rendered_doc: String.t() | nil,
+          docs: [ExDoc.DocNode.t()]
         }
 end

lib/ex_doc/retriever.ex

@@ -141,14 +141,16 @@ defmodule ExDoc.Retriever do
     group_for_doc = config.group_for_doc
     annotations_for_docs = config.annotations_for_docs
 
-    {docs, docs_groups} = get_docs(module_data, source, group_for_doc, annotations_for_docs)
+    {docs, nodes_groups} = get_docs(module_data, source, group_for_doc, annotations_for_docs)
+    docs = ExDoc.Utils.natural_sort_by(docs, &"#{&1.name}/#{&1.arity}")
 
     moduledoc_groups = Map.get(metadata, :groups, [])
 
     docs_groups =
       get_docs_groups(
         moduledoc_groups ++ config.docs_groups ++ module_data.default_groups,
-        docs_groups
+        nodes_groups,
+        docs
       )
 
     metadata = Map.put(metadata, :kind, module_data.type)
@@ -165,8 +167,9 @@ defmodule ExDoc.Retriever do
       type: module_data.type,
       deprecated: metadata[:deprecated],
       docs_groups: docs_groups,
-      docs: ExDoc.Utils.natural_sort_by(docs, &"#{&1.name}/#{&1.arity}"),
-      doc: normalize_doc_ast(doc_ast, "module-"),
+      docs: docs,
+      doc_format: format,
+      doc: doc,
       source_doc: source_doc,
       source_format: format,
       moduledoc_line: doc_line,
@@ -281,13 +284,14 @@ defmodule ExDoc.Retriever do
     end)
   end
 
-  defp get_docs_groups(module_groups, nodes_groups) do
+  defp get_docs_groups(module_groups, nodes_groups, doc_nodes) do
     module_groups = Enum.map(module_groups, &normalize_group/1)
 
     # Doc nodes already have normalized groups
     nodes_groups_descriptions = Map.new(nodes_groups, &{&1.title, &1.description})
 
     normal_groups = module_groups ++ nodes_groups
+    nodes_by_group_title = Enum.group_by(doc_nodes, & &1.group)
 
     {docs_groups, _} =
       Enum.flat_map_reduce(normal_groups, %{}, fn
@@ -296,14 +300,21 @@ defmodule ExDoc.Retriever do
 
         group, seen ->
           seen = Map.put(seen, group.title, true)
-          group = finalize_group(group, nodes_groups_descriptions)
-          {[group], seen}
+
+          case Map.get(nodes_by_group_title, group.title, []) do
+            [] ->
+              {[], seen}
+
+            child_nodes ->
+              group = finalize_group(group, child_nodes, nodes_groups_descriptions)
+              {[group], seen}
+          end
       end)
 
     docs_groups
   end
 
-  defp finalize_group(group, description_fallbacks) do
+  defp finalize_group(group, doc_nodes, description_fallbacks) do
     description =
       case group.description do
         nil -> Map.get(description_fallbacks, group.title)
@@ -320,7 +331,7 @@ defmodule ExDoc.Retriever do
       title: group.title,
       description: description,
       doc: doc_ast,
-      rendered_doc: nil
+      docs: doc_nodes
     }
   end
 

test/ex_doc/group_matcher_test.exs

@@ -2,16 +2,6 @@ defmodule ExDoc.GroupMatcherTest do
   use ExUnit.Case, async: true
   import ExDoc.GroupMatcher
 
-  describe "group_by" do
-    test "group by given data with leftovers" do
-      assert group_by([1, 3, 5], [%{key: 1}, %{key: 3}, %{key: 2}], & &1.key) == [
-               {1, [%{key: 1}]},
-               {3, [%{key: 3}]},
-               {2, [%{key: 2}]}
-             ]
-    end
-  end
-
   describe "module matching" do
     test "by atom names" do
       patterns = [

test/ex_doc/retriever/erlang_test.exs

@@ -59,7 +59,7 @@ defmodule ExDoc.Retriever.ErlangTest do
                moduledoc_line: 2,
                moduledoc_file: moduledoc_file,
                docs: [equiv_function2, function1, function2],
-               docs_groups: [%{title: "Types"}, %{title: "Callbacks"}, %{title: "Functions"}],
+               docs_groups: [%{title: "Functions"}],
                group: nil,
                id: "mod",
                language: ExDoc.Language.Erlang,
@@ -393,7 +393,7 @@ defmodule ExDoc.Retriever.ErlangTest do
         deprecated: nil,
         moduledoc_line: _,
         docs: [function1, function2],
-        docs_groups: [%{title: "Types"}, %{title: "Callbacks"}, %{title: "Functions"}],
+        docs_groups: [%{title: "Functions"}],
         group: nil,
         id: "mod",
         language: ExDoc.Language.Erlang,

test/ex_doc/retriever_test.exs

@@ -140,7 +140,7 @@ defmodule ExDoc.RetrieverTest do
 
       {[mod], []} = Retriever.docs_from_modules([A], config)
 
-      assert [c, b, types, callbacks, functions, a] = mod.docs_groups
+      assert [c, b, a] = mod.docs_groups
 
       # Description returned by the function should override nil
       assert %{title: "c", description: "for c"} = c
@@ -149,10 +149,6 @@ defmodule ExDoc.RetrieverTest do
       # description from @moduledoc
       assert %{title: "b", description: "predefined b"} = b
 
-      assert %{title: "Types", description: nil} = types
-      assert %{title: "Callbacks", description: nil} = callbacks
-      assert %{title: "Functions", description: nil} = functions
-
       # Description returned by th function should define a description
       # for leftover groups
       assert %{title: "a", description: "for a"} = a
@@ -189,9 +185,6 @@ defmodule ExDoc.RetrieverTest do
       assert [
                %{description: nil, title: "c"},
                %{description: "text for b", title: "b"},
-               %{description: nil, title: "Types"},
-               %{description: nil, title: "Callbacks"},
-               %{description: nil, title: "Functions"},
                %{description: nil, title: "a"}
              ] = mod.docs_groups
     end