Tackle some TODOs

lib/ex_doc/autolink.ex

@@ -104,7 +104,6 @@ defmodule ExDoc.Autolink do
     end
   end
 
-  # TODO: make more generic
   @doc false
   def ex_doc_app_url(module, config, path, ext, suffix) do
     if app = app(module) do

lib/ex_doc/config.ex

@@ -98,7 +98,7 @@ defmodule ExDoc.Config do
 
     options =
       if groups_for_functions = options[:groups_for_functions] do
-        # TODO: Deprecate me
+        IO.warn(":groups_for_functions is deprecated, please use :groups_for_docs instead")
         Keyword.put_new(options, :groups_for_docs, groups_for_functions)
       else
         options
@@ -150,7 +150,7 @@ defmodule ExDoc.Config do
   end
 
   defp deprecated?(metadata), do: metadata[:deprecated] != nil
-  defp exception?(metadata), do: metadata[:__doc__] == :exception
+  defp exception?(metadata), do: metadata[:kind] == :exception
 
   defp normalize_nest_modules_by_prefix(nest_modules_by_prefix) do
     nest_modules_by_prefix

lib/ex_doc/formatter/html.ex

@@ -25,6 +25,7 @@ defmodule ExDoc.Formatter.HTML do
     static_files = generate_assets(config, @assets_dir, default_assets(config))
     search_data = generate_search_data(project_nodes, extras, config)
 
+    # TODO: Move this categorization to the language
     nodes_map = %{
       modules: filter_list(:module, project_nodes),
       tasks: filter_list(:task, project_nodes)
@@ -589,7 +590,6 @@ defmodule ExDoc.Formatter.HTML do
     end
   end
 
-  # TODO: Move this categorization to the language
   def filter_list(:module, nodes) do
     Enum.filter(nodes, &(&1.type != :task))
   end

lib/ex_doc/language.ex

@@ -127,7 +127,8 @@ defmodule ExDoc.Language do
                 source_line: non_neg_integer(),
                 source_file: String.t() | nil,
                 signature: [binary()],
-                spec: spec_ast()
+                spec: spec_ast(),
+                extra_annotations: [String.t()]
               }
 
   @doc """

lib/ex_doc/language/elixir.ex

@@ -194,7 +194,8 @@ defmodule ExDoc.Language.Elixir do
       source_line: line,
       source_file: source,
       spec: quoted,
-      signature: signature
+      signature: signature,
+      extra_annotations: []
     }
   end
 
@@ -381,8 +382,6 @@ defmodule ExDoc.Language.Elixir do
   def autolink_spec(ast, opts) do
     config = struct!(Autolink, opts)
 
-    # TODO: re-use ExDoc.Language.Erlang.autolink_spec/2
-
     string =
       ast
       |> Macro.to_string()

lib/ex_doc/language/erlang.ex

@@ -151,15 +151,17 @@ defmodule ExDoc.Language.Erlang do
           source_line: map.source_line,
           source_file: map.source_file,
           spec: map.attr,
-          signature: signature
+          signature: signature,
+          extra_annotations: []
         }
 
       nil ->
         %{
           type: kind,
           source_line: Source.anno_line(anno),
           spec: nil,
-          signature: signature
+          signature: signature,
+          extra_annotations: []
         }
     end
   end

lib/ex_doc/retriever.ex

@@ -138,8 +138,8 @@ defmodule ExDoc.Retriever do
     groups_for_docs =
       config.groups_for_docs ++
         [
-          Types: &(&1[:__doc__] == :type),
-          Callbacks: &(&1[:__doc__] == :callback),
+          Types: &(&1[:kind] in [:type, :opaque]),
+          Callbacks: &(&1[:kind] in [:callback, :macrocallback]),
           Functions: fn _ -> true end
         ]
 
@@ -154,7 +154,7 @@ defmodule ExDoc.Retriever do
 
     types = get_types(module_data, source, groups_for_docs, annotations_for_docs)
 
-    metadata = Map.put(metadata, :__doc__, module_data.type)
+    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}
 
@@ -343,8 +343,6 @@ defmodule ExDoc.Retriever do
 
     doc_ast = doc_ast(content_type, source_doc, file: doc_file, line: doc_line + 1)
 
-    metadata = Map.put(metadata, :__doc__, :callback)
-
     group =
       GroupMatcher.match_function(
         groups_for_docs,
@@ -396,16 +394,14 @@ defmodule ExDoc.Retriever do
     source_url =
       source_link(type_data[:source_file], source, type_data.source_line)
 
-    annotations = annotations_from_metadata(metadata, module_metadata)
-
     signature = signature(type_data.signature)
 
     annotations =
       annotations_for_docs.(metadata) ++
-        if type_data.type == :opaque, do: ["opaque" | annotations], else: annotations
+        annotations_from_metadata(metadata, module_metadata) ++
+        type_data.extra_annotations
 
     doc_ast = doc_ast(content_type, source_doc, file: doc_file, line: doc_line + 1)
-    metadata = Map.put(metadata, :__doc__, :type)
 
     group =
       GroupMatcher.match_function(

test/ex_doc/formatter/html/templates_test.exs

@@ -554,7 +554,6 @@ defmodule ExDoc.Formatter.HTML.TemplatesTest do
       assert content =~
                ~s[Basic type: <a href=\"https://hexdocs.pm/elixir/typespecs.html#basic-types\"><code class=\"inline\">atom/0</code></a>.]
 
-      assert content =~ ~r{opaque/0.*<span class="note">\(opaque\)</span>}ms
       assert content =~ ~r{<span class="attribute">@opaque</span> opaque}
     end
 

test/ex_doc/language/erlang_test.exs

@@ -107,8 +107,6 @@ defmodule ExDoc.Language.ErlangTest do
                ~s|<a href="https://www.erlang.org/doc/man/array.html#new-0"><code>array:new/0</code></a>|
     end
 
-    # TODO: test callbacks. No support in EDoc, use :docgen_xml_to_chunks.
-
     test "external function", c do
       assert autolink_edoc("{@link 'Elixir.EarmarkParser':as_ast/2}", c) ==
                ~s|<a href="https://hexdocs.pm/earmark_parser/EarmarkParser.html#as_ast/2"><code>'Elixir.EarmarkParser':as_ast/2</code></a>|

test/ex_doc/retriever/elixir_test.exs

@@ -207,6 +207,7 @@ defmodule ExDoc.Retriever.ElixirTest do
       assert type1.id == "t:type1/0"
       assert type1.signature == "type1()"
       assert type1.type == :type
+      assert type1.group == :Types
       assert type1.annotations == []
       assert type1.doc_line == 2
       assert DocAST.to_string(type1.doc) == "<p>type1/0 docs.</p>"
@@ -215,7 +216,7 @@ defmodule ExDoc.Retriever.ElixirTest do
       assert opaque1.id == "t:opaque1/0"
       assert opaque1.signature == "opaque1()"
       assert opaque1.type == :opaque
-      assert opaque1.annotations == ["opaque"]
+      assert opaque1.group == :Types
       assert opaque1.doc_line == 5
       assert opaque1.doc |> DocAST.to_string() == ~s|<p>opaque1/0 docs.</p>|
       assert opaque1.spec |> Macro.to_string() == "opaque1()"

test/ex_doc/retriever/erlang_test.exs

@@ -235,6 +235,7 @@ defmodule ExDoc.Retriever.ErlangTest do
       assert callback1.id == "c:callback1/0"
       assert callback1.type == :callback
       assert callback1.annotations == []
+      assert callback1.group == :Callbacks
       assert DocAST.to_string(callback1.doc) =~ "callback1/0 docs."
       assert Path.basename(callback1.source_url) == "mod.erl:4"
 
@@ -243,6 +244,7 @@ defmodule ExDoc.Retriever.ErlangTest do
 
       assert optional_callback1.id == "c:optional_callback1/0"
       assert optional_callback1.type == :callback
+      assert optional_callback1.group == :Callbacks
       assert optional_callback1.annotations == ["optional"]
     end
 
@@ -264,6 +266,7 @@ defmodule ExDoc.Retriever.ErlangTest do
 
       assert opaque1.id == "t:opaque1/0"
       assert opaque1.type == :opaque
+      assert opaque1.group == :Types
       assert opaque1.signature == "opaque1()"
       assert opaque1.doc |> DocAST.to_string() =~ "opaque1/0 docs."
 
@@ -272,6 +275,7 @@ defmodule ExDoc.Retriever.ErlangTest do
 
       assert type1.id == "t:type1/0"
       assert type1.type == :type
+      assert type1.group == :Types
       assert type1.signature == "type1()"
       assert type1.doc |> DocAST.to_string() =~ "type1/0 docs."