From 9e3f220a230e3f649c3b7653fb8513fb56f783c4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Valim?= Date: Thu, 8 Feb 2024 09:33:28 +0100 Subject: [PATCH] Tackle some TODOs --- lib/ex_doc/autolink.ex | 1 - lib/ex_doc/config.ex | 4 ++-- lib/ex_doc/formatter/html.ex | 2 +- lib/ex_doc/language.ex | 3 ++- lib/ex_doc/language/elixir.ex | 5 ++--- lib/ex_doc/language/erlang.ex | 6 ++++-- lib/ex_doc/retriever.ex | 14 +++++--------- test/ex_doc/formatter/html/templates_test.exs | 1 - test/ex_doc/language/erlang_test.exs | 2 -- test/ex_doc/retriever/elixir_test.exs | 3 ++- test/ex_doc/retriever/erlang_test.exs | 4 ++++ 11 files changed, 22 insertions(+), 23 deletions(-) diff --git a/lib/ex_doc/autolink.ex b/lib/ex_doc/autolink.ex index 715310607..70c3c823e 100644 --- a/lib/ex_doc/autolink.ex +++ b/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 diff --git a/lib/ex_doc/config.ex b/lib/ex_doc/config.ex index c380406cc..2c5ee7640 100644 --- a/lib/ex_doc/config.ex +++ b/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 diff --git a/lib/ex_doc/formatter/html.ex b/lib/ex_doc/formatter/html.ex index 371bfb73c..5fa8a63a3 100644 --- a/lib/ex_doc/formatter/html.ex +++ b/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 diff --git a/lib/ex_doc/language.ex b/lib/ex_doc/language.ex index 5927372e1..76cd60ffd 100644 --- a/lib/ex_doc/language.ex +++ b/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 """ diff --git a/lib/ex_doc/language/elixir.ex b/lib/ex_doc/language/elixir.ex index 26d9852a8..62673391c 100644 --- a/lib/ex_doc/language/elixir.ex +++ b/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() diff --git a/lib/ex_doc/language/erlang.ex b/lib/ex_doc/language/erlang.ex index 0ce04065a..8a6bffcb2 100644 --- a/lib/ex_doc/language/erlang.ex +++ b/lib/ex_doc/language/erlang.ex @@ -151,7 +151,8 @@ 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 -> @@ -159,7 +160,8 @@ defmodule ExDoc.Language.Erlang do type: kind, source_line: Source.anno_line(anno), spec: nil, - signature: signature + signature: signature, + extra_annotations: [] } end end diff --git a/lib/ex_doc/retriever.ex b/lib/ex_doc/retriever.ex index 7f944e07f..22f233fd7 100644 --- a/lib/ex_doc/retriever.ex +++ b/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( diff --git a/test/ex_doc/formatter/html/templates_test.exs b/test/ex_doc/formatter/html/templates_test.exs index 924396ea3..4873684c5 100644 --- a/test/ex_doc/formatter/html/templates_test.exs +++ b/test/ex_doc/formatter/html/templates_test.exs @@ -554,7 +554,6 @@ defmodule ExDoc.Formatter.HTML.TemplatesTest do assert content =~ ~s[Basic type: atom/0.] - assert content =~ ~r{opaque/0.*\(opaque\)}ms assert content =~ ~r{@opaque opaque} end diff --git a/test/ex_doc/language/erlang_test.exs b/test/ex_doc/language/erlang_test.exs index e968310d7..7d596aec1 100644 --- a/test/ex_doc/language/erlang_test.exs +++ b/test/ex_doc/language/erlang_test.exs @@ -107,8 +107,6 @@ defmodule ExDoc.Language.ErlangTest do ~s|array:new/0| 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|'Elixir.EarmarkParser':as_ast/2| diff --git a/test/ex_doc/retriever/elixir_test.exs b/test/ex_doc/retriever/elixir_test.exs index ddb132848..ea7008594 100644 --- a/test/ex_doc/retriever/elixir_test.exs +++ b/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) == "

type1/0 docs.

" @@ -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|

opaque1/0 docs.

| assert opaque1.spec |> Macro.to_string() == "opaque1()" diff --git a/test/ex_doc/retriever/erlang_test.exs b/test/ex_doc/retriever/erlang_test.exs index a795389f3..f1061837c 100644 --- a/test/ex_doc/retriever/erlang_test.exs +++ b/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."