Allow groups to carry descriptions

Author: lud

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

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

lib/ex_doc/formatter/html/templates.ex

@@ -134,7 +134,7 @@ defmodule ExDoc.Formatter.HTML.Templates do
         %{id: id, title: node.signature, anchor: URI.encode(node.id), deprecated: deprecated?}
       end
 
-    %{key: text_to_id(group), name: group, nodes: nodes}
+    %{key: text_to_id(group.title), name: group.title, nodes: nodes}
   end
 
   defp module_sections(%ExDoc.ModuleNode{rendered_doc: nil}), do: [sections: []]
@@ -169,7 +169,14 @@ defmodule ExDoc.Formatter.HTML.Templates do
 
   def module_summary(module_node) do
     # TODO: Maybe it should be moved to retriever and it already returned grouped metadata
-    ExDoc.GroupMatcher.group_by(module_node.docs_groups, module_node.docs, & &1.group)
+
+    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
 
   defp favicon_path(%{favicon: nil}), do: nil

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

@@ -39,17 +39,17 @@
       </a>
       <span class="text">Summary</span>
     </h1>
-    <%= for {name, nodes} <- summary, do: summary_template(name, nodes) %>
+    <%= for {group, nodes} <- summary, do: summary_template(group.title, nodes) %>
   </section>
 <% end %>
 
-<%= for {name, nodes} <- summary, key = text_to_id(name) do %>
+<%= for {group, nodes} <- summary, key = text_to_id(group.title) do %>
   <section id="<%= key %>" class="details-list">
     <h1 class="section-heading">
       <a class="hover-link" href="#<%= key %>">
         <i class="ri-link-m" aria-hidden="true"></i>
       </a>
-      <span class="text"><%= name %></span>
+      <span class="text"><%= group.title %></span>
     </h1>
     <div class="<%= key %>-list">
       <%= for node <- nodes, do: detail_template(node, module) %>

lib/ex_doc/group_matcher.ex

@@ -15,7 +15,7 @@ defmodule ExDoc.GroupMatcher do
   end
 
   @doc """
-  Group the following entries and while preserving the order in `groups`.
+  Group the following entries while preserving the order in `groups`.
   """
   def group_by(groups, entries, by) do
     entries = Enum.group_by(entries, by)

lib/ex_doc/nodes.ex

@@ -26,6 +26,10 @@ defmodule ExDoc.ModuleNode do
             metadata: nil
 
   @typep annotation :: atom()
+  @typep doc_group :: %{
+           title: String.t() | atom(),
+           description: String.t() | nil
+         }
 
   @type t :: %__MODULE__{
           id: String.t(),
@@ -43,7 +47,7 @@ defmodule ExDoc.ModuleNode do
           moduledoc_file: String.t(),
           source_path: String.t() | nil,
           source_url: String.t() | nil,
-          docs_groups: [atom()],
+          docs_groups: [doc_group],
           docs: [ExDoc.DocNode.t()],
           typespecs: [ExDoc.DocNode.t()],
           type: atom(),

lib/ex_doc/retriever.ex

@@ -141,6 +141,12 @@ defmodule ExDoc.Retriever do
     annotations_for_docs = config.annotations_for_docs
 
     docs = get_docs(module_data, source, group_for_doc, annotations_for_docs)
+
+    moduledoc_groups = Map.get(metadata, :groups, [])
+
+    {docs_groups, docs} =
+      get_docs_groups(moduledoc_groups ++ config.docs_groups ++ module_data.default_groups, docs)
+
     metadata = Map.put(metadata, :kind, module_data.type)
     group = GroupMatcher.match_module(config.groups_for_modules, module, module_data.id, metadata)
     {nested_title, nested_context} = module_data.nesting_info || {nil, nil}
@@ -154,7 +160,7 @@ defmodule ExDoc.Retriever do
       module: module,
       type: module_data.type,
       deprecated: metadata[:deprecated],
-      docs_groups: config.docs_groups ++ module_data.default_groups,
+      docs_groups: docs_groups,
       docs: ExDoc.Utils.natural_sort_by(docs, &"#{&1.name}/#{&1.arity}"),
       doc_format: format,
       doc: doc,
@@ -198,6 +204,30 @@ defmodule ExDoc.Retriever do
     filter_defaults(nodes)
   end
 
+  defp get_docs_groups(module_groups, doc_nodes) do
+    module_groups = Enum.map(module_groups, &normalize_group/1)
+
+    # Doc nodes already have normalized groups
+    nodes_groups = Enum.map(doc_nodes, & &1.group)
+
+    normal_groups = module_groups ++ nodes_groups
+
+    {docs_groups, _} =
+      Enum.flat_map_reduce(normal_groups, %{}, fn group, seen ->
+        if is_map_key(seen, group.title) do
+          {[], seen}
+        else
+          {[group], Map.put(seen, group.title, true)}
+        end
+      end)
+
+    # We do not need the full group data in each doc node anymore, only the
+    # title.
+    doc_nodes = Enum.map(doc_nodes, &Map.put(&1, :group, &1.group.title))
+
+    {docs_groups, doc_nodes}
+  end
+
   defp get_doc(doc, doc_data, module_data, source, group_for_doc, annotations_for_docs) do
     {:docs_v1, _, _, content_type, _, module_metadata, _} = module_data.docs
     {{type, name, arity}, anno, _signature, source_doc, metadata} = doc
@@ -222,7 +252,7 @@ defmodule ExDoc.Retriever do
       (source_doc && doc_ast(content_type, source_doc, file: doc_file, line: doc_line + 1)) ||
         doc_data.doc_fallback.()
 
-    group = group_for_doc.(metadata) || doc_data.default_group
+    group = normalize_group(group_for_doc.(metadata) || doc_data.default_group)
 
     %ExDoc.DocNode{
       id: doc_data.id_key <> nil_or_name(name, arity),
@@ -314,4 +344,15 @@ defmodule ExDoc.Retriever do
   defp source_link(%{url_pattern: url_pattern, relative_path: path}, line) do
     url_pattern.(path, line)
   end
+
+  defp normalize_group(group) do
+    case group do
+      %{title: title, description: description}
+      when is_binary(title) and (is_binary(description) or is_nil(description)) ->
+        group
+
+      title when is_binary(title) when is_atom(title) ->
+        %{title: title, description: nil}
+    end
+  end
 end

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: ["Types", "Callbacks", "Functions"],
+               docs_groups: [%{title: "Types"}, %{title: "Callbacks"}, %{title: "Functions"}],
                group: nil,
                id: "mod",
                language: ExDoc.Language.Erlang,
@@ -156,7 +156,7 @@ defmodule ExDoc.Retriever.ErlangTest do
                moduledoc_line: 6,
                moduledoc_file: moduledoc_file,
                docs: [type, callback, function],
-               docs_groups: ["Types", "Callbacks", "Functions"],
+               docs_groups: [%{title: "Types"}, %{title: "Callbacks"}, %{title: "Functions"}],
                group: nil,
                id: "mod",
                language: ExDoc.Language.Erlang,
@@ -397,7 +397,7 @@ defmodule ExDoc.Retriever.ErlangTest do
         deprecated: nil,
         moduledoc_line: _,
         docs: [function1, function2],
-        docs_groups: ["Types", "Callbacks", "Functions"],
+        docs_groups: [%{title: "Types"}, %{title: "Callbacks"}, %{title: "Functions"}],
         group: nil,
         id: "mod",
         language: ExDoc.Language.Erlang,

test/ex_doc/retriever_test.exs

@@ -108,6 +108,38 @@ defmodule ExDoc.RetrieverTest do
       assert %{id: "baz/0", group: "c"} = baz
     end
 
+    test "function groups description use moduledoc :groups metadata", c do
+      elixirc(c, ~S"""
+      defmodule A do
+        @moduledoc groups: [
+          "c",
+          %{title: "b", description: "text for b"}
+        ]
+
+        @doc group: "a"
+        @callback foo() :: :ok
+
+        @doc group: "b"
+        def bar(), do: :ok
+
+        @doc group: "c"
+        def baz(), do: :ok
+      end
+      """)
+
+      config = %ExDoc.Config{}
+      {[mod], []} = Retriever.docs_from_modules([A], config)
+
+      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
+
     test "function annotations", c do
       elixirc(c, ~S"""
       defmodule A do