Merge callback and function processing

Author: josevalim

lib/ex_doc/language.ex

@@ -8,6 +8,8 @@ defmodule ExDoc.Language do
 
     * `:module` - the module
 
+    * `:default_groups` - the default groups used by this module
+
     * `:docs` - the docs chunk
 
     * `:language` - the language callback
@@ -24,15 +26,14 @@ defmodule ExDoc.Language do
 
     * `:source_basedir` - the absolute directory where the Elixir/Erlang compiler was run.
 
-    * `:callback_types` - a list of types that are considered callbacks
-
     * `:nesting_info` - a `{nested_title, nested_context}` tuple or `nil`.
       For example, `"A.B.C"` becomes `{"C", "A.B."}`.
 
     * `:private` - a map with language-specific data
   """
   @type module_data() :: %{
           module: module(),
+          default_groups: [binary()],
           docs: tuple(),
           language: module(),
           id: String.t(),
@@ -41,7 +42,6 @@ defmodule ExDoc.Language do
           source_basedir: String.t(),
           source_file: String.t() | nil,
           source_line: non_neg_integer(),
-          callback_types: [atom()],
           nesting_info: {String.t(), String.t()} | nil,
           private: map()
         }
@@ -52,58 +52,42 @@ defmodule ExDoc.Language do
   @callback module_data(module(), tuple(), ExDoc.Config.t()) :: module_data() | false
 
   @doc """
-  Returns a map with function information or `false`.
+  Returns a map with documentation information about a given node or `false`.
 
   The map has the following keys:
 
-    * `:source_line` - the line where the code is located, def/defp in Elixir, foo(...) in Erlang
-
-    * `:source_file` - the source file where the code in located
+    * `:id_key` - the key used to namespace this entry
 
-    * `:specs` - a list of specs that will be later formatted by `c:typespec/2`
+    * `:default_group` - the default group this definition falls under
 
     * `:doc_fallback` - if set, a 0-arity function that returns DocAST which
        will be used as fallback to empty docs on the function node
 
     * `:extra_annotations` - additional annotations
 
-  """
-  @callback function_data(entry :: tuple(), module_data()) ::
-              %{
-                source_line: non_neg_integer() | nil,
-                source_file: String.t() | nil,
-                specs: [spec_ast()],
-                # TODO: change to following on Elixir 1.15. It trips mix formatter between 1.14 and 1.15
-                # doc_fallback: (-> ExDoc.DocAST.t()) | nil,
-                doc_fallback: (... -> ExDoc.DocAST.t()) | nil,
-                extra_annotations: [String.t()]
-              }
-              | false
-
-  @doc """
-  Returns a map with callback information.
-
-  The map has the following keys:
-
-    * `:source_line` - the line where the code is located
+    * `:signature` - the function signature
 
     * `:source_file` - the source file where the code in located
 
-    * `:signature` - the signature
+    * `:source_line` - the line where the code is located, def/defp in Elixir, foo(...) in Erlang
 
     * `:specs` - a list of specs that will be later formatted by `c:typespec/2`
 
-    * `:extra_annotations` - additional annotations
-
   """
-  @callback callback_data(entry :: tuple(), module_data()) ::
+  @callback doc_data(entry :: tuple(), module_data()) ::
               %{
-                source_line: non_neg_integer() | nil,
-                source_file: String.t() | nil,
+                id_key: binary(),
+                default_group: binary(),
+                # TODO: change to following on Elixir 1.15. It trips mix formatter between 1.14 and 1.15
+                # doc_fallback: (-> ExDoc.DocAST.t()),
+                doc_fallback: (... -> ExDoc.DocAST.t()),
+                extra_annotations: [String.t()],
                 signature: [binary()],
-                specs: [spec_ast()],
-                extra_annotations: [String.t()]
+                source_file: String.t() | nil,
+                source_line: non_neg_integer() | nil,
+                specs: [spec_ast()]
               }
+              | false
 
   @doc """
   Returns a map with type information.
@@ -120,9 +104,14 @@ defmodule ExDoc.Language do
 
     * `:spec` - a spec that will be later formatted by `c:typespec/2`
   """
+  # TODO: Convert TypeNode into FunctionNode and rename FunctionNode to DocNode
+  # TODO: Merge this into doc_data
   @callback type_data(entry :: tuple(), spec :: term()) ::
               %{
                 type: :type | :opaque | :nominal,
+                # TODO: change to following on Elixir 1.15. It trips mix formatter between 1.14 and 1.15
+                # doc_fallback: (-> ExDoc.DocAST.t()),
+                doc_fallback: (... -> ExDoc.DocAST.t()),
                 source_line: non_neg_integer(),
                 source_file: String.t() | nil,
                 signature: [binary()],

lib/ex_doc/language/elixir.ex

@@ -10,7 +10,6 @@ defmodule ExDoc.Language.Elixir do
   @spec module_data(atom, any, any) ::
           false
           | %{
-              callback_types: [:callback, ...],
               docs: any,
               id: binary,
               language: ExDoc.Language.Erlang,
@@ -48,6 +47,7 @@ defmodule ExDoc.Language.Elixir do
 
         %{
           module: module,
+          default_groups: ~w(Types Callbacks Functions),
           docs: docs_chunk,
           language: __MODULE__,
           id: inspect(module),
@@ -56,7 +56,6 @@ defmodule ExDoc.Language.Elixir do
           source_line: source_line,
           source_file: source_file,
           source_basedir: source_basedir,
-          callback_types: [:callback, :macrocallback],
           nesting_info: nesting_info(title, config.nest_modules_by_prefix),
           private: %{
             abst_code: abst_code,
@@ -78,17 +77,30 @@ defmodule ExDoc.Language.Elixir do
   end
 
   @impl true
-  def function_data(entry, module_data) do
-    {{kind, name, arity}, anno, _signature, _doc_content, metadata} = entry
+  def doc_data(entry, %{type: type} = module_data) do
+    case entry do
+      {_key, _anno, _sig, :hidden, _metadata} ->
+        false
 
-    if doc?(entry, module_data.type) do
-      function_data(kind, name, arity, anno, metadata, module_data)
-    else
-      false
+      {{_kind, name, _arity}, _anno, _sig, _doc, _metadata}
+      when name in [:impl_for, :impl_for!] and type == :protocol ->
+        false
+
+      {{kind, _, _}, _anon, _sig, _doc, _metadata} when kind in [:function, :macro] ->
+        function_data(entry, module_data)
+
+      {{kind, _, _}, _anon, _sig, _doc, _metadata}
+      when kind in [:callback, :macrocallback] and type != :protocol ->
+        callback_data(entry, module_data)
+
+      _ ->
+        false
     end
   end
 
-  defp function_data(kind, name, arity, anno, metadata, module_data) do
+  defp function_data(entry, module_data) do
+    {{kind, name, arity}, anno, signature, _doc_content, metadata} = entry
+
     extra_annotations =
       case {kind, name, arity} do
         {:macro, _, _} -> ["macro"]
@@ -99,35 +111,23 @@ defmodule ExDoc.Language.Elixir do
     actual_def = actual_def(name, arity, kind)
 
     %{
+      id_key: "",
+      default_group: "Functions",
       doc_fallback: fn ->
         impl = Map.fetch(module_data.private.impls, actual_def)
 
         callback_doc_ast(name, arity, impl) ||
           delegate_doc_ast(metadata[:delegate_to])
       end,
       extra_annotations: extra_annotations,
+      signature: signature,
+      source_file: nil,
       source_line: find_function_line(module_data, actual_def) || Source.anno_line(anno),
       specs: specs(kind, name, actual_def, module_data)
     }
   end
 
-  # We are only interested in functions and macros for now
-  defp doc?({{kind, _, _}, _, _, _, _}, _) when kind not in [:function, :macro] do
-    false
-  end
-
-  # Skip impl_for and impl_for! for protocols
-  defp doc?({{_, name, _}, _, _, _, _}, :protocol) when name in [:impl_for, :impl_for!] do
-    false
-  end
-
-  # If content is a map, then it is ok.
-  defp doc?({_, _, _, doc, _}, _) do
-    doc != :hidden
-  end
-
-  @impl true
-  def callback_data(entry, module_data) do
+  defp callback_data(entry, module_data) do
     {{kind, name, arity}, anno, _signature, _doc, _metadata} = entry
     actual_def = actual_def(name, arity, kind)
 
@@ -149,16 +149,18 @@ defmodule ExDoc.Language.Elixir do
       end
 
     line = Source.anno_line(anno)
-
     quoted = Enum.map(specs, &Code.Typespec.spec_to_quoted(name, &1))
     signature = [get_typespec_signature(hd(quoted), arity)]
 
     %{
-      source_line: line,
-      source_file: nil,
+      id_key: "c:",
+      default_group: "Callbacks",
+      doc_fallback: fn -> nil end,
+      extra_annotations: extra_annotations,
       signature: signature,
-      specs: quoted,
-      extra_annotations: extra_annotations
+      source_file: nil,
+      source_line: line,
+      specs: quoted
     }
   end
 
@@ -182,6 +184,7 @@ defmodule ExDoc.Language.Elixir do
 
     %{
       type: type,
+      doc_fallback: fn -> nil end,
       source_line: line,
       source_file: source,
       spec: quoted,
@@ -282,7 +285,7 @@ defmodule ExDoc.Language.Elixir do
         {:local, :..}
 
       ["//", "", ""] ->
-        {:local, :"..//"}
+        {:local, :..//}
 
       ["", ""] ->
         {:local, :.}