Allow unknown groups to be handled

Author: josevalim

lib/ex_doc/formatter/html.ex

@@ -383,7 +383,7 @@ defmodule ExDoc.Formatter.HTML do
       if ids_count[extra.id] > 1, do: {disambiguate_id(extra, idx), idx + 1}, else: {extra, idx}
     end)
     |> elem(0)
-    |> Enum.sort_by(fn extra -> GroupMatcher.group_index(groups, extra.group) end)
+    |> Enum.sort_by(fn extra -> GroupMatcher.index(groups, extra.group) end)
   end
 
   def generate_redirects(config, ext) do

lib/ex_doc/formatter/html/templates.ex

@@ -203,13 +203,12 @@ defmodule ExDoc.Formatter.HTML.Templates do
   end
 
   def module_summary(module_node) do
-    entries = docs_groups(module_node.docs_groups, module_node.docs ++ module_node.typespecs)
-
-    Enum.reject(entries, fn {_type, nodes} -> nodes == [] end)
-  end
-
-  defp docs_groups(groups, docs) do
-    for group <- groups, do: {group, Enum.filter(docs, &(&1.group == group))}
+    # 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 ++ module_node.typespecs,
+      & &1.group
+    )
   end
 
   defp logo_path(%{logo: nil}), do: nil

lib/ex_doc/group_matcher.ex

@@ -8,15 +8,32 @@ defmodule ExDoc.GroupMatcher do
   @doc """
   Finds the index of a given group.
   """
-  def group_index(groups, group) do
+  def index(groups, group) do
     Enum.find_index(groups, fn {k, _v} -> k == group end) || -1
   end
 
+  @doc """
+  Group the following entries and 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 function.
   """
-  @spec match_function(group_patterns, map) :: atom() | nil
-  def match_function(group_patterns, metadata) do
+  @spec match_doc(group_patterns, map) :: atom() | nil
+  def match_doc(group_patterns, metadata) do
     match_group_patterns(group_patterns, fn pattern -> pattern.(metadata) end)
   end
 

lib/ex_doc/retriever.ex

@@ -69,7 +69,7 @@ defmodule ExDoc.Retriever do
 
   defp sort_modules(modules, config) when is_list(modules) do
     Enum.sort_by(modules, fn module ->
-      {GroupMatcher.group_index(config.groups_for_modules, module.group), module.nested_context,
+      {GroupMatcher.index(config.groups_for_modules, module.group), module.nested_context,
        module.nested_title, module.id}
     end)
   end
@@ -135,21 +135,14 @@ defmodule ExDoc.Retriever do
     {doc_line, doc_file, format, source_doc, doc, metadata} = get_module_docs(module_data, source)
 
     # TODO: The default function groups must be returned by the language
-    groups_for_docs =
-      config.groups_for_docs ++
-        [
-          Types: &(&1[:kind] in [:type, :opaque, :nominal]),
-          Callbacks: &(&1[:kind] in [:callback, :macrocallback]),
-          Functions: fn _ -> true end
-        ]
-
+    groups_for_docs = config.groups_for_docs
     annotations_for_docs = config.annotations_for_docs
 
-    docs_groups = Enum.map(groups_for_docs, &elem(&1, 0)) |> Enum.uniq()
-    function_docs = get_docs(module_data, source, groups_for_docs, annotations_for_docs)
+    docs_groups =
+      Enum.uniq(Enum.map(groups_for_docs, &elem(&1, 0)) ++ [:Types, :Callbacks, :Functions])
 
     docs =
-      function_docs ++
+      get_docs(module_data, source, groups_for_docs, annotations_for_docs) ++
         get_callbacks(module_data, source, groups_for_docs, annotations_for_docs)
 
     types = get_types(module_data, source, groups_for_docs, annotations_for_docs)
@@ -259,7 +252,7 @@ defmodule ExDoc.Retriever do
       (source_doc && doc_ast(content_type, source_doc, file: doc_file, line: doc_line + 1)) ||
         function_data.doc_fallback.()
 
-    group = GroupMatcher.match_function(groups_for_docs, metadata)
+    group = GroupMatcher.match_doc(groups_for_docs, metadata) || :Functions
 
     %ExDoc.FunctionNode{
       id: nil_or_name(name, arity),
@@ -342,11 +335,7 @@ defmodule ExDoc.Retriever do
       doc_ast(content_type, source_doc, file: doc_file, line: doc_line + 1) ||
         doc_fallback(callback_data)
 
-    group =
-      GroupMatcher.match_function(
-        groups_for_docs,
-        metadata
-      )
+    group = GroupMatcher.match_doc(groups_for_docs, metadata) || :Callbacks
 
     %ExDoc.FunctionNode{
       id: "c:" <> nil_or_name(name, arity),
@@ -403,11 +392,7 @@ defmodule ExDoc.Retriever do
       doc_ast(content_type, source_doc, file: doc_file, line: doc_line + 1) ||
         doc_fallback(type_data)
 
-    group =
-      GroupMatcher.match_function(
-        groups_for_docs,
-        metadata
-      )
+    group = GroupMatcher.match_doc(groups_for_docs, metadata) || :Types
 
     %ExDoc.TypeNode{
       id: "t:" <> nil_or_name(name, arity),

test/ex_doc/group_matcher_test.exs

@@ -2,8 +2,18 @@ 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 "match modules by their atom names" do
+    test "by atom names" do
       patterns = [
         Group: [MyApp.SomeModule, :lists]
       ]
@@ -22,7 +32,7 @@ defmodule ExDoc.GroupMatcherTest do
                nil
     end
 
-    test "match modules by their string names" do
+    test "by string names" do
       patterns = [
         Group: ["MyApp.SomeModule", ":lists"]
       ]
@@ -36,7 +46,7 @@ defmodule ExDoc.GroupMatcherTest do
                nil
     end
 
-    test "match modules by regular expressions" do
+    test "by regular expressions" do
       patterns = [
         Group: ~r/MyApp\..?/
       ]
@@ -53,7 +63,7 @@ defmodule ExDoc.GroupMatcherTest do
   end
 
   describe "extras matching" do
-    test "it can match extra files by their string names" do
+    test "by string names" do
       patterns = [
         Group: ["docs/handling/testing.md"]
       ]
@@ -62,7 +72,7 @@ defmodule ExDoc.GroupMatcherTest do
       assert match_extra(patterns, "docs/handling/setup.md") == nil
     end
 
-    test "it can match extra files by regular expressions" do
+    test "by regular expressions" do
       patterns = [
         Group: ~r/docs\/handling?/
       ]