Unify handling of docs for groups

Author: josevalim

lib/ex_doc/config.ex

@@ -23,16 +23,16 @@ defmodule ExDoc.Config do
             before_closing_head_tag: &__MODULE__.before_closing_head_tag/1,
             canonical: nil,
             cover: nil,
-            default_group_for_doc: &__MODULE__.default_group_for_doc/1,
             deps: [],
+            docs_groups: [],
             extra_section: nil,
             extras: [],
             favicon: nil,
             filter_modules: &__MODULE__.filter_modules/2,
             formatter: "html",
             formatters: [],
+            group_for_doc: &__MODULE__.default_group_for_doc/1,
             groups_for_extras: [],
-            groups_for_docs: [],
             groups_for_modules: [],
             homepage_url: nil,
             language: "en",
@@ -67,16 +67,16 @@ defmodule ExDoc.Config do
           before_closing_head_tag: (atom() -> String.t()) | mfa() | map(),
           canonical: nil | String.t(),
           cover: nil | Path.t(),
-          default_group_for_doc: (keyword() -> String.t() | nil),
           deps: [{ebin_path :: String.t(), doc_url :: String.t()}],
+          docs_groups: [String.t()],
           extra_section: nil | String.t(),
           extras: list(),
           favicon: nil | Path.t(),
           filter_modules: (module, map -> boolean),
           formatter: nil | String.t(),
           formatters: [String.t()],
+          group_for_doc: (keyword() -> String.t() | nil),
           groups_for_extras: [{binary(), term()}],
-          groups_for_docs: [{binary(), (keyword() -> boolean)}],
           groups_for_modules: [{binary(), term()}],
           homepage_url: nil | String.t(),
           language: String.t(),
@@ -113,13 +113,17 @@ defmodule ExDoc.Config do
         options
       end
 
+    apps = Keyword.get(options, :apps, [])
+
     {groups_for_docs, options} = Keyword.pop(options, :groups_for_docs, [])
     {groups_for_extras, options} = Keyword.pop(options, :groups_for_extras, [])
-    apps = Keyword.get(options, :apps, [])
 
     {groups_for_modules, options} =
       Keyword.pop(options, :groups_for_modules, default_groups_for_modules(apps))
 
+    {default_group_for_doc, options} =
+      Keyword.pop(options, :default_group_for_doc, &default_group_for_doc/1)
+
     {skip_undefined_reference_warnings_on, options} =
       Keyword.pop(
         options,
@@ -137,7 +141,8 @@ defmodule ExDoc.Config do
 
     preconfig = %__MODULE__{
       filter_modules: normalize_filter_modules(filter_modules),
-      groups_for_docs: normalize_groups(groups_for_docs),
+      docs_groups: for({group, _} <- groups_for_docs, do: to_string(group)),
+      group_for_doc: normalize_groups_for_docs(groups_for_docs, default_group_for_doc),
       groups_for_extras: normalize_groups(groups_for_extras),
       groups_for_modules:
         normalize_groups(
@@ -176,6 +181,16 @@ defmodule ExDoc.Config do
     raise ArgumentError, "#{inspect(proglang)} is not supported"
   end
 
+  defp normalize_groups_for_docs(groups, default) do
+    groups = normalize_groups(groups)
+
+    fn metadata ->
+      Enum.find_value(groups, fn {group, function} ->
+        function.(metadata) && group
+      end) || default.(metadata)
+    end
+  end
+
   defp normalize_groups(groups) do
     for {k, v} <- groups, do: {to_string(k), v}
   end

lib/ex_doc/group_matcher.ex

@@ -31,14 +31,6 @@ defmodule ExDoc.GroupMatcher do
     groups ++ Enum.sort(leftovers)
   end
 
-  @doc """
-  Finds a matching group for the given function.
-  """
-  def match_doc(group_patterns, callback, default, metadata) do
-    match_group_patterns(group_patterns, fn pattern -> pattern.(metadata) end) ||
-      callback.(metadata) || default
-  end
-
   @doc """
   Finds a matching group for the given module name, id, and metadata.
   """

lib/ex_doc/retriever.ex

@@ -137,14 +137,10 @@ defmodule ExDoc.Retriever do
 
     {doc_line, doc_file, format, source_doc, doc, metadata} = get_module_docs(module_data, source)
 
-    default_group = config.default_group_for_doc
-    groups_for_docs = config.groups_for_docs
+    group_for_doc = config.group_for_doc
     annotations_for_docs = config.annotations_for_docs
 
-    docs_groups =
-      Enum.uniq(Enum.map(groups_for_docs, &elem(&1, 0)) ++ module_data.default_groups)
-
-    docs = get_docs(module_data, source, default_group, groups_for_docs, annotations_for_docs)
+    docs = get_docs(module_data, source, group_for_doc, annotations_for_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}
@@ -158,7 +154,7 @@ defmodule ExDoc.Retriever do
       module: module,
       type: module_data.type,
       deprecated: metadata[:deprecated],
-      docs_groups: docs_groups,
+      docs_groups: config.docs_groups ++ module_data.default_groups,
       docs: ExDoc.Utils.natural_sort_by(docs, &"#{&1.name}/#{&1.arity}"),
       doc_format: format,
       doc: doc,
@@ -190,35 +186,19 @@ defmodule ExDoc.Retriever do
     {doc_line, doc_file, format, moduledoc, doc_ast(format, moduledoc, options), metadata}
   end
 
-  defp get_docs(module_data, source, default_group, groups_for_docs, annotations_for_docs) do
+  defp get_docs(module_data, source, group_for_doc, annotations_for_docs) do
     {:docs_v1, _, _, _, _, _, docs} = module_data.docs
 
     nodes =
       for doc <- docs,
           doc_data = module_data.language.doc_data(doc, module_data) do
-        get_doc(
-          doc,
-          doc_data,
-          module_data,
-          source,
-          default_group,
-          groups_for_docs,
-          annotations_for_docs
-        )
+        get_doc(doc, doc_data, module_data, source, group_for_doc, annotations_for_docs)
       end
 
     filter_defaults(nodes)
   end
 
-  defp get_doc(
-         doc,
-         doc_data,
-         module_data,
-         source,
-         default_group,
-         groups_for_docs,
-         annotations_for_docs
-       ) do
+  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
     doc_file = anno_file(anno, source)
@@ -242,8 +222,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 =
-      GroupMatcher.match_doc(groups_for_docs, default_group, doc_data.default_group, metadata)
+    group = group_for_doc.(metadata) || doc_data.default_group
 
     %ExDoc.DocNode{
       id: doc_data.id_key <> nil_or_name(name, arity),

mix.lock

@@ -1,5 +1,5 @@
 %{
-  "earmark_parser": {:hex, :earmark_parser, "1.4.43", "34b2f401fe473080e39ff2b90feb8ddfeef7639f8ee0bbf71bb41911831d77c5", [:mix], [], "hexpm", "970a3cd19503f5e8e527a190662be2cee5d98eed1ff72ed9b3d1a3d466692de8"},
+  "earmark_parser": {:hex, :earmark_parser, "1.4.44", "f20830dd6b5c77afe2b063777ddbbff09f9759396500cdbe7523efd58d7a339c", [:mix], [], "hexpm", "4778ac752b4701a5599215f7030989c989ffdc4f6df457c5f36938cc2d2a2750"},
   "easyhtml": {:hex, :easyhtml, "0.3.2", "050adfc8074f53b261f7dfe83303d864f1fbf5988245b369f8fdff1bf4c4b3e6", [:mix], [{:floki, "~> 0.35", [hex: :floki, repo: "hexpm", optional: false]}], "hexpm", "b6a936f91612a4870aa3e828cd8da5a08d9e3b6221b4d3012b6ec70b87845d06"},
   "floki": {:hex, :floki, "0.36.2", "a7da0193538c93f937714a6704369711998a51a6164a222d710ebd54020aa7a3", [:mix], [], "hexpm", "a8766c0bc92f074e5cb36c4f9961982eda84c5d2b8e979ca67f5c268ec8ed580"},
   "jason": {:hex, :jason, "1.4.4", "b9226785a9aa77b6857ca22832cffa5d5011a667207eb2a0ad56adb5db443b8a", [:mix], [{:decimal, "~> 1.0 or ~> 2.0", [hex: :decimal, repo: "hexpm", optional: true]}], "hexpm", "c5eb0cab91f094599f94d55bc63409236a8ec69a21a67814529e8d5f6cc90b3b"},

test/ex_doc/config_test.exs

@@ -114,6 +114,16 @@ defmodule ExDoc.ConfigTest do
       assert config.source_url_pattern.("foo.ex", 123) == "a123bfoo.exc"
     end
 
+    test "groups_for_docs" do
+      config =
+        build(groups_for_docs: [Foo: &(&1[:section] == "foo"), Bar: &(&1[:section] == "bar")])
+
+      assert config.group_for_doc.(section: "foo") == "Foo"
+      assert config.group_for_doc.(section: "bar") == "Bar"
+      assert config.group_for_doc.(section: "baz") == nil
+      assert config.docs_groups == ~w(Foo Bar)
+    end
+
     test "groups_for_modules" do
       # Using real applications, since we load them to extract the corresponding list of modules
       stdlib = :stdlib

test/ex_doc/formatter/epub/templates_test.exs

@@ -127,10 +127,14 @@ defmodule ExDoc.Formatter.EPUB.TemplatesTest do
     test "outputs function groups" do
       content =
         get_module_page([CompiledWithDocs],
-          groups_for_docs: [
-            "Example functions": &(&1[:purpose] == :example),
-            Legacy: &is_binary(&1[:deprecated])
-          ]
+          group_for_doc: fn metadata ->
+            cond do
+              metadata[:purpose] == :example -> "Example functions"
+              is_binary(metadata[:deprecated]) -> "Legacy"
+              true -> "Functions"
+            end
+          end,
+          docs_groups: ["Example functions", "Legacy"]
         )
 
       assert content =~ ~r{id="example-functions".*Example functions}ms

test/ex_doc/formatter/html/templates_test.exs

@@ -303,10 +303,14 @@ defmodule ExDoc.Formatter.HTML.TemplatesTest do
         ExDoc.Retriever.docs_from_modules(
           [CompiledWithDocs, CompiledWithDocs.Nested],
           doc_config(context,
-            groups_for_docs: [
-              "Example functions": &(&1[:purpose] == :example),
-              Legacy: &is_binary(&1[:deprecated])
-            ]
+            group_for_doc: fn metadata ->
+              cond do
+                metadata[:purpose] == :example -> "Example functions"
+                is_binary(metadata[:deprecated]) -> "Legacy"
+                true -> "Functions"
+              end
+            end,
+            docs_groups: ["Example functions", "Legacy"]
           )
         )
 
@@ -484,10 +488,13 @@ defmodule ExDoc.Formatter.HTML.TemplatesTest do
     test "outputs function groups", context do
       content =
         get_module_page([CompiledWithDocs], context,
-          groups_for_docs: [
-            "Example functions": &(&1[:purpose] == :example),
-            Legacy: &is_binary(&1[:deprecated])
-          ]
+          group_for_doc: fn metadata ->
+            cond do
+              metadata[:purpose] == :example -> "Example functions"
+              is_binary(metadata[:deprecated]) -> "Legacy"
+              true -> "Functions"
+            end
+          end
         )
 
       doc = EasyHTML.parse!(content)

test/ex_doc/retriever_test.exs

@@ -62,35 +62,6 @@ defmodule ExDoc.RetrieverTest do
       assert %{module: Qux, group: nil} = qux
     end
 
-    test "function groups", c do
-      elixirc(c, ~S"""
-      defmodule A do
-        @doc group: 1
-        def foo(), do: :ok
-
-        @doc group: 1
-        def bar(), do: :ok
-
-        @doc group: 2
-        def baz(), do: :ok
-      end
-      """)
-
-      config = %ExDoc.Config{
-        groups_for_docs: [
-          {"Group 1", &(&1.group == 1)},
-          {"Group 2", &(&1.group == 2)}
-        ]
-      }
-
-      {[mod], []} = Retriever.docs_from_modules([A], config)
-      [bar, baz, foo] = mod.docs
-
-      assert %{id: "foo/0", group: "Group 1"} = foo
-      assert %{id: "bar/0", group: "Group 1"} = bar
-      assert %{id: "baz/0", group: "Group 2"} = baz
-    end
-
     test "function groups use :group metadata", c do
       elixirc(c, ~S"""
       defmodule A do
@@ -128,7 +99,7 @@ defmodule ExDoc.RetrieverTest do
       end
       """)
 
-      config = %ExDoc.Config{default_group_for_doc: & &1[:semi_group]}
+      config = %ExDoc.Config{group_for_doc: & &1[:semi_group]}
       {[mod], []} = Retriever.docs_from_modules([A], config)
       [bar, baz, foo] = mod.docs