Add :default_group_for_doc

Author: josevalim

lib/ex_doc/config.ex

@@ -3,6 +3,7 @@ defmodule ExDoc.Config do
 
   # Defaults
   @default_source_ref "main"
+  def default_group_for_doc(metadata), do: metadata[:group]
   def filter_modules(_module, _metadata), do: true
   def before_closing_head_tag(_), do: ""
   def before_closing_footer_tag(_), do: ""
@@ -21,6 +22,7 @@ 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: [],
             extra_section: nil,
             extras: [],
@@ -63,15 +65,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()}],
           extra_section: nil | String.t(),
           extras: list(),
           filter_modules: (module, map -> boolean),
           formatter: nil | String.t(),
           formatters: [String.t()],
-          groups_for_extras: keyword(),
-          groups_for_docs: keyword((keyword() -> boolean)),
-          groups_for_modules: keyword(),
+          groups_for_extras: [{binary(), term()}],
+          groups_for_docs: [{binary(), (keyword() -> boolean)}],
+          groups_for_modules: [{binary(), term()}],
           homepage_url: nil | String.t(),
           language: String.t(),
           logo: nil | Path.t(),
@@ -96,7 +99,6 @@ defmodule ExDoc.Config do
   @spec build(String.t(), String.t(), Keyword.t()) :: ExDoc.Config.t()
   def build(project, vsn, options) do
     {output, options} = Keyword.pop(options, :output, "./doc")
-    {groups_for_modules, options} = Keyword.pop(options, :groups_for_modules, [])
     {nest_modules_by_prefix, options} = Keyword.pop(options, :nest_modules_by_prefix, [])
     {proglang, options} = Keyword.pop(options, :proglang, :elixir)
     {filter_modules, options} = Keyword.pop(options, :filter_modules, &filter_modules/2)
@@ -109,6 +111,10 @@ defmodule ExDoc.Config do
         options
       end
 
+    {groups_for_docs, options} = Keyword.pop(options, :groups_for_docs, [])
+    {groups_for_extras, options} = Keyword.pop(options, :groups_for_extras, [])
+    {groups_for_modules, options} = Keyword.pop(options, :groups_for_modules, [])
+
     {skip_undefined_reference_warnings_on, options} =
       Keyword.pop(
         options,
@@ -126,7 +132,13 @@ defmodule ExDoc.Config do
 
     preconfig = %__MODULE__{
       filter_modules: normalize_filter_modules(filter_modules),
-      groups_for_modules: normalize_groups_for_modules(groups_for_modules),
+      groups_for_docs: normalize_groups(groups_for_docs),
+      groups_for_extras: normalize_groups(groups_for_extras),
+      groups_for_modules:
+        normalize_groups(
+          # TODO: The default module groups must be returned by the language
+          groups_for_modules ++ [Deprecated: &deprecated?/1, Exceptions: &exception?/1]
+        ),
       homepage_url: options[:homepage_url],
       main: options[:main],
       nest_modules_by_prefix: normalize_nest_modules_by_prefix(nest_modules_by_prefix),
@@ -159,12 +171,8 @@ defmodule ExDoc.Config do
     raise ArgumentError, "#{inspect(proglang)} is not supported"
   end
 
-  # TODO: The default module groups must be returned by the language
-  defp normalize_groups_for_modules(groups_for_modules) do
-    default_groups = [Deprecated: &deprecated?/1, Exceptions: &exception?/1]
-
-    groups_for_modules ++
-      Enum.reject(default_groups, fn {k, _} -> Keyword.has_key?(groups_for_modules, k) end)
+  defp normalize_groups(groups) do
+    for {k, v} <- groups, do: {to_string(k), v}
   end
 
   defp deprecated?(metadata), do: metadata[:deprecated] != nil

lib/ex_doc/group_matcher.ex

@@ -32,15 +32,14 @@ defmodule ExDoc.GroupMatcher do
   @doc """
   Finds a matching group for the given function.
   """
-  @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)
+  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.
   """
-  @spec match_module(group_patterns, module, binary, map) :: atom() | nil
   def match_module(group_patterns, module, id, metadata) do
     match_group_patterns(group_patterns, fn pattern ->
       case pattern do
@@ -55,7 +54,6 @@ defmodule ExDoc.GroupMatcher do
   @doc """
   Finds a matching group for the given extra filename
   """
-  @spec match_extra(group_patterns, binary) :: atom() | nil
   def match_extra(group_patterns, filename) do
     match_group_patterns(group_patterns, fn pattern ->
       case pattern do

lib/ex_doc/language.ex

@@ -49,10 +49,10 @@ defmodule ExDoc.Language do
   @doc """
   Returns a map with module information.
   """
-  @callback module_data(module(), tuple(), ExDoc.Config.t()) :: module_data() | :skip
+  @callback module_data(module(), tuple(), ExDoc.Config.t()) :: module_data() | false
 
   @doc """
-  Returns a map with function information or an atom `:skip`.
+  Returns a map with function information or `false`.
 
   The map has the following keys:
 
@@ -78,7 +78,7 @@ defmodule ExDoc.Language do
                 doc_fallback: (... -> ExDoc.DocAST.t()) | nil,
                 extra_annotations: [String.t()]
               }
-              | :skip
+              | false
 
   @doc """
   Returns a map with callback information.

lib/ex_doc/language/elixir.ex

@@ -8,7 +8,7 @@ defmodule ExDoc.Language.Elixir do
 
   @impl true
   @spec module_data(atom, any, any) ::
-          :skip
+          false
           | %{
               callback_types: [:callback, ...],
               docs: any,
@@ -34,7 +34,7 @@ defmodule ExDoc.Language.Elixir do
 
     cond do
       skip ->
-        :skip
+        false
 
       abst_code = Source.get_abstract_code(module) ->
         title = module_title(module, type)
@@ -73,7 +73,7 @@ defmodule ExDoc.Language.Elixir do
           []
         )
 
-        :skip
+        false
     end
   end
 
@@ -84,7 +84,7 @@ defmodule ExDoc.Language.Elixir do
     if doc?(entry, module_data.type) do
       function_data(kind, name, arity, anno, metadata, module_data)
     else
-      :skip
+      false
     end
   end
 
@@ -282,7 +282,7 @@ defmodule ExDoc.Language.Elixir do
         {:local, :..}
 
       ["//", "", ""] ->
-        {:local, :"..//"}
+        {:local, :..//}
 
       ["", ""] ->
         {:local, :.}

lib/ex_doc/language/erlang.ex

@@ -8,7 +8,7 @@ defmodule ExDoc.Language.Erlang do
 
   @impl true
   @spec module_data(atom, any, any) ::
-          :skip
+          false
           | %{
               callback_types: [:callback, ...],
               docs: any,
@@ -54,7 +54,7 @@ defmodule ExDoc.Language.Erlang do
       }
     else
       ExDoc.Utils.warn("skipping docs for module #{inspect(module)}, reason: :no_debug_info", [])
-      :skip
+      false
     end
   end
 
@@ -68,7 +68,7 @@ defmodule ExDoc.Language.Erlang do
          function_exported?(module_data.module, name, arity) do
       function_data(name, arity, doc_content, module_data, metadata)
     else
-      :skip
+      false
     end
   end
 

lib/ex_doc/retriever.ex

@@ -135,17 +135,18 @@ 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
+    default_group = config.default_group_for_doc
     groups_for_docs = config.groups_for_docs
     annotations_for_docs = config.annotations_for_docs
 
     docs_groups =
-      Enum.uniq(Enum.map(groups_for_docs, &elem(&1, 0)) ++ [:Types, :Callbacks, :Functions])
+      Enum.uniq(Enum.map(groups_for_docs, &elem(&1, 0)) ++ ~w(Types Callbacks Functions))
 
     docs =
-      get_docs(module_data, source, groups_for_docs, annotations_for_docs) ++
-        get_callbacks(module_data, source, groups_for_docs, annotations_for_docs)
+      get_docs(module_data, source, default_group, groups_for_docs, annotations_for_docs) ++
+        get_callbacks(module_data, source, default_group, groups_for_docs, annotations_for_docs)
 
-    types = get_types(module_data, source, groups_for_docs, annotations_for_docs)
+    types = get_types(module_data, source, default_group, groups_for_docs, annotations_for_docs)
 
     metadata = Map.put(metadata, :kind, module_data.type)
     group = GroupMatcher.match_module(config.groups_for_modules, module, module_data.id, metadata)
@@ -195,42 +196,37 @@ defmodule ExDoc.Retriever do
 
   ## Function helpers
 
-  defp get_docs(module_data, source, groups_for_docs, annotations_for_docs) do
-    {:docs_v1, _, _, _, _, _, doc_elements} = module_data.docs
+  defp get_docs(module_data, source, default_group, groups_for_docs, annotations_for_docs) do
+    {:docs_v1, _, _, _, _, _, docs} = module_data.docs
 
     nodes =
-      Enum.flat_map(doc_elements, fn doc_element ->
-        case module_data.language.function_data(doc_element, module_data) do
-          :skip ->
-            []
-
-          function_data ->
-            [
-              get_function(
-                doc_element,
-                function_data,
-                source,
-                module_data,
-                groups_for_docs,
-                annotations_for_docs
-              )
-            ]
-        end
-      end)
+      for doc <- docs,
+          function_data = module_data.language.function_data(doc, module_data) do
+        get_function(
+          doc,
+          function_data,
+          module_data,
+          source,
+          default_group,
+          groups_for_docs,
+          annotations_for_docs
+        )
+      end
 
     filter_defaults(nodes)
   end
 
   defp get_function(
-         doc_element,
+         doc,
          function_data,
-         source,
          module_data,
+         source,
+         default_group,
          groups_for_docs,
          annotations_for_docs
        ) do
     {:docs_v1, _, _, content_type, _, module_metadata, _} = module_data.docs
-    {{type, name, arity}, anno, signature, source_doc, metadata} = doc_element
+    {{type, name, arity}, anno, signature, source_doc, metadata} = doc
     doc_file = anno_file(anno, source)
     doc_line = anno_line(anno)
 
@@ -252,7 +248,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_doc(groups_for_docs, metadata) || :Functions
+    group = GroupMatcher.match_doc(groups_for_docs, default_group, "Functions", metadata)
 
     %ExDoc.FunctionNode{
       id: nil_or_name(name, arity),
@@ -296,23 +292,31 @@ defmodule ExDoc.Retriever do
   defp get_callbacks(
          %{type: :behaviour} = module_data,
          source,
+         default_group,
          groups_for_docs,
          annotations_for_docs
        ) do
     {:docs_v1, _, _, _, _, _, docs} = module_data.docs
 
     for {{kind, _, _}, _, _, _, _} = doc <- docs, kind in module_data.callback_types do
-      get_callback(doc, source, groups_for_docs, module_data, annotations_for_docs)
+      get_callback(doc, module_data, source, default_group, groups_for_docs, annotations_for_docs)
     end
   end
 
-  defp get_callbacks(_, _, _, _), do: []
+  defp get_callbacks(_, _, _, _, _), do: []
 
-  defp get_callback(callback, source, groups_for_docs, module_data, annotations_for_docs) do
-    callback_data = module_data.language.callback_data(callback, module_data)
+  defp get_callback(
+         doc,
+         module_data,
+         source,
+         default_group,
+         groups_for_docs,
+         annotations_for_docs
+       ) do
+    callback_data = module_data.language.callback_data(doc, module_data)
 
     {:docs_v1, _, _, content_type, _, module_metadata, _} = module_data.docs
-    {{kind, name, arity}, anno, _signature, source_doc, metadata} = callback
+    {{kind, name, arity}, anno, _signature, source_doc, metadata} = doc
     doc_file = anno_file(anno, source)
     doc_line = anno_line(anno)
 
@@ -335,7 +339,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_doc(groups_for_docs, metadata) || :Callbacks
+    group = GroupMatcher.match_doc(groups_for_docs, default_group, "Callbacks", metadata)
 
     %ExDoc.FunctionNode{
       id: "c:" <> nil_or_name(name, arity),
@@ -357,21 +361,21 @@ defmodule ExDoc.Retriever do
 
   ## Typespecs
 
-  defp get_types(module_data, source, groups_for_docs, annotations_for_docs) do
+  defp get_types(module_data, source, default_group, groups_for_docs, annotations_for_docs) do
     {:docs_v1, _, _, _, _, _, docs} = module_data.docs
 
     for {{:type, _, _}, _, _, content, _} = doc <- docs, content != :hidden do
-      get_type(doc, source, groups_for_docs, module_data, annotations_for_docs)
+      get_type(doc, module_data, source, default_group, groups_for_docs, annotations_for_docs)
     end
   end
 
-  defp get_type(type_entry, source, groups_for_docs, module_data, annotations_for_docs) do
+  defp get_type(doc, module_data, source, default_group, groups_for_docs, annotations_for_docs) do
     {:docs_v1, _, _, content_type, _, module_metadata, _} = module_data.docs
-    {{kind, name, arity}, anno, _signature, source_doc, metadata} = type_entry
+    {{kind, name, arity}, anno, _signature, source_doc, metadata} = doc
     doc_file = anno_file(anno, source)
     doc_line = anno_line(anno)
 
-    type_data = module_data.language.type_data(type_entry, module_data)
+    type_data = module_data.language.type_data(doc, module_data)
 
     metadata =
       Map.merge(
@@ -392,7 +396,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_doc(groups_for_docs, metadata) || :Types
+    group = GroupMatcher.match_doc(groups_for_docs, default_group, "Types", metadata)
 
     %ExDoc.TypeNode{
       id: "t:" <> nil_or_name(name, arity),