Accept groups descriptions from callback

Author: lud

lib/ex_doc/retriever.ex

@@ -209,16 +209,29 @@ defmodule ExDoc.Retriever do
 
     # Doc nodes already have normalized groups
     nodes_groups = Enum.map(doc_nodes, & &1.group)
+    nodes_groups_descriptions = Map.new(nodes_groups, &{&1.title, &1.description})
 
     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
+      Enum.flat_map_reduce(normal_groups, %{}, fn
+        group, seen when is_map_key(seen, group.title) ->
           {[], seen}
-        else
-          {[group], Map.put(seen, group.title, true)}
-        end
+
+        group, seen ->
+          seen = Map.put(seen, group.title, group.description)
+
+          group =
+            case group do
+              %{description: nil} ->
+                description = Map.get(nodes_groups_descriptions, group.title, nil)
+                Map.put(group, :description, description)
+
+              _ ->
+                group
+            end
+
+          {[group], seen}
       end)
 
     # We do not need the full group data in each doc node anymore, only the
@@ -351,6 +364,10 @@ defmodule ExDoc.Retriever do
       when is_binary(title) and (is_binary(description) or is_nil(description)) ->
         group
 
+      kw when is_list(kw) ->
+        true = Keyword.keyword?(kw)
+        %{title: Keyword.fetch!(kw, :title), description: kw[:description]}
+
       title when is_binary(title) when is_atom(title) ->
         %{title: title, description: nil}
     end

test/ex_doc/retriever_test.exs

@@ -108,6 +108,62 @@ defmodule ExDoc.RetrieverTest do
       assert %{id: "baz/0", group: "c"} = baz
     end
 
+    test "default_group_for_doc can return group description from @moduledoc", c do
+      elixirc(c, ~S"""
+      defmodule A do
+
+        @moduledoc groups: [
+          "c",
+          %{title: "b", description: "predefined b"}
+        ]
+
+        @doc test_group: "a"
+        @callback foo() :: :ok
+
+        @doc test_group: "b"
+        def bar(), do: :ok
+
+        @doc test_group: "c"
+        def baz(), do: :ok
+      end
+      """)
+
+      config = %ExDoc.Config{
+        group_for_doc: fn meta ->
+          case meta[:test_group] do
+            "a" -> [title: "a", description: "for a"]
+            "b" -> [title: "b", description: "ignored description"]
+            "c" -> [title: "c", description: "for c"]
+          end
+        end
+      }
+
+      {[mod], []} = Retriever.docs_from_modules([A], config)
+
+      assert [c, b, types, callbacks, functions, a] = mod.docs_groups
+
+      # Description returned by the function should override nil
+      assert %{title: "c", description: "for c"} = c
+
+      # Description returned by the function should not override a
+      # 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
+
+      [bar, baz, foo] = mod.docs
+
+      assert %{id: "c:foo/0", group: "a"} = foo
+      assert %{id: "bar/0", group: "b"} = bar
+      assert %{id: "baz/0", group: "c"} = baz
+    end
+
     test "function groups description use moduledoc :groups metadata", c do
       elixirc(c, ~S"""
       defmodule A do