Merge TypeNode into FunctionNode as DocNode

Author: josevalim

lib/ex_doc/formatter/html.ex

@@ -101,39 +101,17 @@ defmodule ExDoc.Formatter.HTML do
                   id: id,
                   line: child_node.doc_line,
                   file: child_node.doc_file,
-                  current_kfa: {:function, child_node.name, child_node.arity}
+                  current_kfa: {child_node.type, child_node.name, child_node.arity}
                 ]
 
             specs = Enum.map(child_node.specs, &language.autolink_spec(&1, autolink_opts))
             child_node = %{child_node | specs: specs}
             render_doc(child_node, language, autolink_opts, opts)
           end
 
-        typespecs =
-          for child_node <- node.typespecs do
-            id = id(node, child_node)
-
-            autolink_opts =
-              autolink_opts ++
-                [
-                  id: id,
-                  line: child_node.doc_line,
-                  file: child_node.doc_file,
-                  current_kfa: {child_node.type, child_node.name, child_node.arity}
-                ]
-
-            child_node = %{
-              child_node
-              | spec: language.autolink_spec(child_node.spec, autolink_opts)
-            }
-
-            render_doc(child_node, language, autolink_opts, opts)
-          end
-
         %{
           render_doc(node, language, [{:id, node.id} | autolink_opts], opts)
-          | docs: docs,
-            typespecs: typespecs
+          | docs: docs
         }
       end,
       timeout: :infinity

lib/ex_doc/formatter/html/search_data.ex

@@ -63,9 +63,8 @@ defmodule ExDoc.Formatter.HTML.SearchData do
         )
       end
 
-    functions = Enum.flat_map(node.docs, &node_child(&1, node))
-    types = Enum.flat_map(node.typespecs, &node_child(&1, node))
-    [module] ++ module_sections ++ functions ++ types
+    docs = Enum.flat_map(node.docs, &node_child(&1, node))
+    [module] ++ module_sections ++ docs
   end
 
   defp node_child(node, module_node) do

lib/ex_doc/formatter/html/templates.ex

@@ -19,39 +19,13 @@ defmodule ExDoc.Formatter.HTML.Templates do
     module_template(config, module_node, summary, nodes_map)
   end
 
-  @doc """
-  Get the full specs from a function, already in HTML form.
-  """
-  def get_specs(%ExDoc.TypeNode{spec: spec}) do
-    [spec]
-  end
-
-  def get_specs(%ExDoc.FunctionNode{specs: specs}) when is_list(specs) do
-    presence(specs)
-  end
-
-  def get_specs(_node) do
-    nil
-  end
-
   @doc """
   Format the attribute type used to define the spec of the given `node`.
   """
   def format_spec_attribute(module, node) do
     module.language.format_spec_attribute(node)
   end
 
-  @doc """
-  Get defaults clauses.
-  """
-  def get_defaults(%{defaults: defaults}) do
-    defaults
-  end
-
-  def get_defaults(_) do
-    []
-  end
-
   @doc """
   Get the pretty name of a function node
   """
@@ -90,9 +64,6 @@ defmodule ExDoc.Formatter.HTML.Templates do
     Regex.replace(~r|(<[^>]*) id="[^"]*"([^>]*>)|, doc, ~S"\1\2", [])
   end
 
-  defp presence([]), do: nil
-  defp presence(other), do: other
-
   defp enc(binary), do: URI.encode(binary)
 
   @doc """
@@ -204,11 +175,7 @@ defmodule ExDoc.Formatter.HTML.Templates do
 
   def module_summary(module_node) do
     # 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
-    )
+    ExDoc.GroupMatcher.group_by(module_node.docs_groups, module_node.docs, & &1.group)
   end
 
   defp logo_path(%{logo: nil}), do: nil

lib/ex_doc/formatter/html/templates/detail_template.eex

@@ -1,5 +1,5 @@
 <section class="detail" id="<%=enc node.id %>">
-  <%= for {default_name, default_arity} <- get_defaults(node) do %>
+  <%= for {default_name, default_arity} <- node.defaults do %>
     <span id="<%=enc "#{default_name}/#{default_arity}" %>"></span>
   <% end %>
   <div class="detail-header">
@@ -23,9 +23,9 @@
   <% end %>
 
   <section class="docstring">
-    <%= if specs = get_specs(node) do %>
+    <%= if node.specs != [] do %>
       <div class="specs">
-        <%= for spec <- specs do %>
+        <%= for spec <- node.specs do %>
           <pre translate="no"><span class="attribute"><%= format_spec_attribute(module, node) %></span> <%= spec %></pre>
         <% end %>
       </div>

lib/ex_doc/language.ex

@@ -73,6 +73,8 @@ defmodule ExDoc.Language do
 
     * `:specs` - a list of specs that will be later formatted by `c:typespec/2`
 
+    * `:type` - the type of the doc (`:function`, `:macro`, `:type`, etc)
+
   """
   @callback doc_data(entry :: tuple(), module_data()) ::
               %{
@@ -85,40 +87,11 @@ defmodule ExDoc.Language do
                 signature: [binary()],
                 source_file: String.t() | nil,
                 source_line: non_neg_integer() | nil,
-                specs: [spec_ast()]
+                specs: [spec_ast()],
+                type: atom()
               }
               | false
 
-  @doc """
-  Returns a map with type information.
-
-  The map has the following keys:
-
-    * `:type` - `:type` or `:opaque` or `:nominal`
-
-    * `:source_line` - the line where the code is located
-
-    * `:source_file` - the source file where the code in located
-
-    * `:signature` - the signature
-
-    * `: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()],
-                spec: spec_ast(),
-                extra_annotations: [String.t()]
-              }
-
   @doc """
   Autolinks docs.
   """
@@ -141,7 +114,7 @@ defmodule ExDoc.Language do
   @doc """
   Return an attribute in the canonical representation.
   """
-  @callback format_spec_attribute(%ExDoc.FunctionNode{} | %ExDoc.TypeNode{}) :: String.t()
+  @callback format_spec_attribute(%ExDoc.DocNode{}) :: String.t()
 
   @doc """
   Parse a module.function string and return it.

lib/ex_doc/language/elixir.ex

@@ -93,6 +93,9 @@ defmodule ExDoc.Language.Elixir do
       when kind in [:callback, :macrocallback] and type != :protocol ->
         callback_data(entry, module_data)
 
+      {{:type, _, _}, _anon, _sig, _doc, _metadata} ->
+        type_data(entry, module_data)
+
       _ ->
         false
     end
@@ -115,15 +118,14 @@ defmodule ExDoc.Language.Elixir do
       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])
+        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)
+      specs: specs(kind, name, actual_def, module_data),
+      type: kind
     }
   end
 
@@ -160,7 +162,8 @@ defmodule ExDoc.Language.Elixir do
       signature: signature,
       source_file: nil,
       source_line: line,
-      specs: quoted
+      specs: quoted,
+      type: kind
     }
   end
 
@@ -172,8 +175,7 @@ defmodule ExDoc.Language.Elixir do
     {:type, num, :fun, [{:type, num, :product, rest_args} | rest]}
   end
 
-  @impl true
-  def type_data(entry, module_data) do
+  defp type_data(entry, module_data) do
     {{_kind, name, arity}, _anno, _signature, _doc, _metadata} = entry
 
     %{type: type, spec: spec, source_file: source, source_line: line} =
@@ -183,13 +185,15 @@ defmodule ExDoc.Language.Elixir do
     signature = [get_typespec_signature(quoted, arity)]
 
     %{
-      type: type,
+      id_key: "t:",
+      default_group: "Types",
       doc_fallback: fn -> nil end,
-      source_line: line,
+      extra_annotations: [],
       source_file: source,
-      spec: quoted,
+      source_line: line,
       signature: signature,
-      extra_annotations: []
+      specs: [quoted],
+      type: type
     }
   end
 
@@ -398,10 +402,12 @@ defmodule ExDoc.Language.Elixir do
   end
 
   @impl true
-  def format_spec_attribute(%ExDoc.TypeNode{type: type}), do: "@#{type}"
-  def format_spec_attribute(%ExDoc.FunctionNode{type: :callback}), do: "@callback"
-  def format_spec_attribute(%ExDoc.FunctionNode{type: :macrocallback}), do: "@macrocallback"
-  def format_spec_attribute(%ExDoc.FunctionNode{}), do: "@spec"
+  def format_spec_attribute(%{type: :type}), do: "@type"
+  def format_spec_attribute(%{type: :opaque}), do: "@opaque"
+  def format_spec_attribute(%{type: :nominal}), do: "@nominal"
+  def format_spec_attribute(%{type: :callback}), do: "@callback"
+  def format_spec_attribute(%{type: :macrocallback}), do: "@macrocallback"
+  def format_spec_attribute(%{}), do: "@spec"
 
   ## Module Helpers
 

lib/ex_doc/language/erlang.ex

@@ -73,6 +73,9 @@ defmodule ExDoc.Language.Erlang do
       kind == :callback ->
         callback_data(name, arity, anno, signature, metadata, module_data)
 
+      kind == :type ->
+        type_data(name, arity, anno, signature, metadata, module_data)
+
       true ->
         false
     end
@@ -104,7 +107,8 @@ defmodule ExDoc.Language.Erlang do
       signature: signature,
       source_file: file,
       source_line: line,
-      specs: specs
+      specs: specs,
+      type: :function
     }
   end
 
@@ -132,40 +136,32 @@ defmodule ExDoc.Language.Erlang do
       signature: signature,
       source_file: file,
       source_line: line,
-      specs: specs
+      specs: specs,
+      type: :callback
     }
   end
 
-  @impl true
-  def type_data(entry, module_data) do
-    {{kind, name, arity}, anno, signature, _doc, metadata} = entry
-
-    case Source.fetch_type!(module_data, name, arity) do
-      %{} = map ->
-        %{
-          doc_fallback: fn ->
-            equiv_data(module_data.module, map.source_file, map.source_line, metadata, "t:")
-          end,
-          type: map.type,
-          source_line: map.source_line,
-          source_file: map.source_file,
-          spec: map.attr,
-          signature: signature,
-          extra_annotations: []
-        }
+  defp type_data(name, arity, anno, signature, metadata, module_data) do
+    {specs, file, line, type} =
+      case Source.fetch_type!(module_data, name, arity) do
+        %{attr: attr, source_file: file, source_line: line, type: type} ->
+          {[attr], file, line, type}
 
-      nil ->
-        %{
-          doc_fallback: fn ->
-            equiv_data(module_data.module, nil, Source.anno_line(anno), metadata, "t:")
-          end,
-          type: kind,
-          source_line: Source.anno_line(anno),
-          spec: nil,
-          signature: signature,
-          extra_annotations: []
-        }
-    end
+        nil ->
+          {[], nil, Source.anno_line(anno), :type}
+      end
+
+    %{
+      id_key: "t:",
+      default_group: "Types",
+      doc_fallback: fn -> equiv_data(module_data.module, file, line, metadata, "t:") end,
+      extra_annotations: [],
+      signature: signature,
+      source_file: file,
+      source_line: line,
+      specs: specs,
+      type: type
+    }
   end
 
   defp equiv_data(module, file, line, metadata, prefix \\ "") do
@@ -263,9 +259,11 @@ defmodule ExDoc.Language.Erlang do
   end
 
   @impl true
-  def format_spec_attribute(%ExDoc.TypeNode{type: type}), do: "-#{type}"
-  def format_spec_attribute(%ExDoc.FunctionNode{type: :callback}), do: "-callback"
-  def format_spec_attribute(%ExDoc.FunctionNode{}), do: "-spec"
+  def format_spec_attribute(%{type: :type}), do: "-type"
+  def format_spec_attribute(%{type: :opaque}), do: "-opaque"
+  def format_spec_attribute(%{type: :nominal}), do: "-nominal"
+  def format_spec_attribute(%{type: :callback}), do: "-callback"
+  def format_spec_attribute(%{}), do: "-spec"
 
   ## Autolink