diff --git a/lib/ex_doc/formatter.ex b/lib/ex_doc/formatter.ex index f8e2dca5e..085ef4a61 100644 --- a/lib/ex_doc/formatter.ex +++ b/lib/ex_doc/formatter.ex @@ -245,7 +245,12 @@ defmodule ExDoc.Formatter do specs = Enum.map(child_node.source_specs, &language.autolink_spec(&1, child_config)) - child_node = %{child_node | specs: specs} + deprecated_doc = + child_node.deprecated && + language.autolink_deprecated(child_node.deprecated, child_config) + + child_node = %{child_node | specs: specs, deprecated_doc: deprecated_doc} + autolink_doc(child_node, language, child_config, highlight_opts) end @@ -259,6 +264,11 @@ defmodule ExDoc.Formatter do line: node.moduledoc_line } + deprecated_doc = + node.deprecated && language.autolink_deprecated(node.deprecated, module_config) + + node = %{node | deprecated_doc: deprecated_doc} + %{ autolink_doc(node, language, module_config, highlight_opts) | docs_groups: docs_groups diff --git a/lib/ex_doc/formatter/epub/templates/module_template.eex b/lib/ex_doc/formatter/epub/templates/module_template.eex index 0626c343a..ac1b0c0ed 100644 --- a/lib/ex_doc/formatter/epub/templates/module_template.eex +++ b/lib/ex_doc/formatter/epub/templates/module_template.eex @@ -3,9 +3,9 @@ <%= H.breakable_module_title(module.title) %> <%= H.module_type(module) %> - <%= if deprecated = module.deprecated do %> + <%= if deprecated = module.deprecated_doc do %>
- This <%= module.type %> is deprecated. <%=h deprecated %>. + This <%= module.type %> is deprecated. <%= deprecated %>.
<% end %> diff --git a/lib/ex_doc/formatter/html/templates/detail_template.eex b/lib/ex_doc/formatter/html/templates/detail_template.eex index a0fd04814..99e9fb56b 100644 --- a/lib/ex_doc/formatter/html/templates/detail_template.eex +++ b/lib/ex_doc/formatter/html/templates/detail_template.eex @@ -18,9 +18,9 @@ <% end %> - <%= if deprecated = node.deprecated do %> + <%= if deprecated = node.deprecated_doc do %>
- This <%= node.type %> is deprecated. <%= h(deprecated) %>. + This <%= node.type %> is deprecated. <%= deprecated %>.
<% end %> diff --git a/lib/ex_doc/formatter/html/templates/module_template.eex b/lib/ex_doc/formatter/html/templates/module_template.eex index 854b547e9..6ba96ce37 100644 --- a/lib/ex_doc/formatter/html/templates/module_template.eex +++ b/lib/ex_doc/formatter/html/templates/module_template.eex @@ -21,9 +21,9 @@ <% end %> - <%= if deprecated = module.deprecated do %> + <%= if deprecated = module.deprecated_doc do %>
- This <%= module.type %> is deprecated. <%= h(deprecated) %>. + This <%= module.type %> is deprecated. <%= deprecated %>.
<% end %> diff --git a/lib/ex_doc/language.ex b/lib/ex_doc/language.ex index 78c4e3000..17f47b05f 100644 --- a/lib/ex_doc/language.ex +++ b/lib/ex_doc/language.ex @@ -94,6 +94,11 @@ defmodule ExDoc.Language do @callback autolink_doc(doc :: ExDoc.DocAST.t(), config :: ExDoc.Autolink.t()) :: ExDoc.DocAST.t() + @doc """ + Autolinks deprecation messages. + """ + @callback autolink_deprecated(message :: String.t(), config :: ExDoc.Autolink.t()) :: iodata() + @doc """ Autolinks typespecs. """ diff --git a/lib/ex_doc/language/elixir.ex b/lib/ex_doc/language/elixir.ex index 0c8db5f3c..5ecd3623e 100644 --- a/lib/ex_doc/language/elixir.ex +++ b/lib/ex_doc/language/elixir.ex @@ -375,6 +375,57 @@ defmodule ExDoc.Language.Elixir do walk_doc(ast, config) end + # Autolinks references within deprecation messages. + # + # Unlike docstrings which are parsed as Markdown AST and require references in backticks (e.g. `foo/1`), + # deprecation messages are arbitrary plain-text strings (e.g. `@deprecated "Use foo/1 instead"`). + # + # Supported patterns: + # * Local functions/macros: `name/arity` (e.g. `to_existing_atom/1`) + # * Remote Elixir functions/macros: `Module.name/arity` (e.g. `String.to_existing_atom/1`) + # * Remote Erlang functions: `:module.name/arity` (e.g. `:re.version/0`) + # + # Patterns supported in `autolink_doc` but intentionally omitted here: + # * Module names (e.g. `MapSet`, `Macro.Env`): omitted to avoid false positives in plain text + # * Prefixed references (e.g. `m:Module`, `t:Mod.type/0`, `c:Mod.callback/1`): not common in deprecation messages + @impl true + def autolink_deprecated(message, %Autolink{} = config) do + config = %{ + config + | force_module_prefix: false, + skip_undefined_reference_warnings_on: fn _ -> true end + } + + regex = ~r{ + (?<=\A|\s) # Preceded by start of string or whitespace + ( # + (?: + (?: + :[a-z][_a-zA-Z0-9]* # Erlang module (e.g. :re) + | + [A-Z][_a-zA-Z0-9]*(?:\.[A-Z][_a-zA-Z0-9]*)* # Elixir module (e.g. String or Macro.Env) + ) + \. # Dot operator + )? + [a-z_][_a-zA-Z0-9]*[!?]? # Function/macro name + /\d+ # /arity + ) # + (?=[\s,.]|\z) # Followed by whitespace, comma, period, or end of string + }x + + escaped = ExDoc.Utils.h(message) + + Regex.replace(regex, escaped, fn _all, ref -> + case Autolink.url(ref, :regular_link, config) do + url when is_binary(url) -> + ~s|#{ref}| + + _ -> + ref + end + end) + end + @impl true def format_spec(ast) do ast diff --git a/lib/ex_doc/language/erlang.ex b/lib/ex_doc/language/erlang.ex index 2fa871e27..97c0f7a45 100644 --- a/lib/ex_doc/language/erlang.ex +++ b/lib/ex_doc/language/erlang.ex @@ -202,6 +202,11 @@ defmodule ExDoc.Language.Erlang do walk_doc(ast, config) end + @impl true + def autolink_deprecated(message, _config) do + ExDoc.Utils.h(message) + end + @impl true def autolink_spec(ast, %Autolink{} = config) do {name, anno, quoted} = diff --git a/lib/ex_doc/nodes.ex b/lib/ex_doc/nodes.ex index ba4650589..4728ea50d 100644 --- a/lib/ex_doc/nodes.ex +++ b/lib/ex_doc/nodes.ex @@ -11,6 +11,7 @@ defmodule ExDoc.ModuleNode do module: nil, group: nil, deprecated: nil, + deprecated_doc: nil, doc: nil, source_doc: nil, source_format: nil, @@ -33,6 +34,7 @@ defmodule ExDoc.ModuleNode do module: module(), group: atom() | nil, deprecated: String.t() | nil, + deprecated_doc: String.t() | nil, doc: ExDoc.DocAST.t() | nil, source_doc: term() | nil, source_format: String.t() | nil, @@ -59,6 +61,7 @@ defmodule ExDoc.DocNode do arity: 0, defaults: [], deprecated: nil, + deprecated_doc: nil, doc: nil, source_doc: nil, type: nil, @@ -81,6 +84,7 @@ defmodule ExDoc.DocNode do arity: non_neg_integer(), defaults: [function_default()], deprecated: String.t() | nil, + deprecated_doc: String.t() | nil, doc: ExDoc.DocAST.t() | nil, source_doc: term() | nil, type: atom(), diff --git a/test/ex_doc/formatter/epub/templates_test.exs b/test/ex_doc/formatter/epub/templates_test.exs index 927834dc2..beaa6c50a 100644 --- a/test/ex_doc/formatter/epub/templates_test.exs +++ b/test/ex_doc/formatter/epub/templates_test.exs @@ -234,6 +234,19 @@ defmodule ExDoc.Formatter.EPUB.TemplatesTest do assert content =~ "

A content example.

" end + test "autolinks deprecation information" do + content = get_module_template([Deprecated]) + + assert content =~ + ~r{
\s*This module is deprecated. Use example_1/0 or String.to_atom/1 instead.} + + assert content =~ + ~r{
\s*This function is deprecated. Use something else instead.} + + assert content =~ + ~r{
\s*This function is deprecated. Use example_1/0 or String.to_atom/1 instead.} + end + test "outputs summaries" do content = get_module_template([CompiledWithDocs]) diff --git a/test/ex_doc/formatter/html/templates_test.exs b/test/ex_doc/formatter/html/templates_test.exs index 1458b35bb..453a9e580 100644 --- a/test/ex_doc/formatter/html/templates_test.exs +++ b/test/ex_doc/formatter/html/templates_test.exs @@ -478,6 +478,27 @@ defmodule ExDoc.Formatter.HTML.TemplatesTest do ~r{
\s*This function is deprecated. Use something else instead.} end + test "autolinks deprecation information", context do + content = get_module_template([Deprecated], context) + + assert content =~ + ~s{deprecated} + + assert content =~ + ~s{deprecated} + + refute content =~ ~s{title="Use \s*This module is deprecated. Use example_1/0 or String.to_atom/1 instead.} + + assert content =~ + ~r{
\s*This function is deprecated. Use something else instead.} + + assert content =~ + ~r{
\s*This function is deprecated. Use example_1/0 or String.to_atom/1 instead.} + end + test "outputs the types and function specs", context do content = get_module_template([TypesAndSpecs, TypesAndSpecs.Sub], context) integer = ~s[integer()] diff --git a/test/ex_doc/formatter/html_test.exs b/test/ex_doc/formatter/html_test.exs index a49d15f68..4adacef59 100644 --- a/test/ex_doc/formatter/html_test.exs +++ b/test/ex_doc/formatter/html_test.exs @@ -98,6 +98,7 @@ defmodule ExDoc.Formatter.HTMLTest do %{"id" => "OverlappingDefaults"}, %{"id" => "TypesAndSpecs"}, %{"id" => "TypesAndSpecs.Sub"}, + %{"id" => "Deprecated"}, %{"id" => "Warnings"}, %{"id" => "RandomError"} ], diff --git a/test/ex_doc/formatter/markdown_test.exs b/test/ex_doc/formatter/markdown_test.exs index b74809996..7b978d101 100644 --- a/test/ex_doc/formatter/markdown_test.exs +++ b/test/ex_doc/formatter/markdown_test.exs @@ -195,6 +195,8 @@ defmodule ExDoc.Formatter.MarkdownTest do assert content =~ """ - Deprecated + - [Deprecated](Deprecated.md): A module for testing deprecations. + - [Warnings](Warnings.md): moduledoc `Warnings.bar/0` - Exceptions diff --git a/test/ex_doc/language/elixir_test.exs b/test/ex_doc/language/elixir_test.exs index cb0d862cc..671845b4b 100644 --- a/test/ex_doc/language/elixir_test.exs +++ b/test/ex_doc/language/elixir_test.exs @@ -469,6 +469,146 @@ defmodule ExDoc.Language.ElixirTest do end end + describe "autolink_deprecated/2" do + test "links local functions" do + ExDoc.Refs.insert([ + {{:module, AutolinkTest.Local}, :public}, + {{:function, AutolinkTest.Local, :to_existing_atom, 1}, :public}, + {{:function, AutolinkTest.Local, :to_unsafe_atom, 1}, :public} + ]) + + msg = "Use to_existing_atom/1 or to_unsafe_atom/1 instead" + + assert autolink_deprecated(msg, current_module: AutolinkTest.Local) == + ~s|Use to_existing_atom/1 or to_unsafe_atom/1 instead| + + assert autolink_deprecated("Use to_existing_atom/1.", current_module: AutolinkTest.Local) == + ~s|Use to_existing_atom/1.| + + msg = "to_existing_atom/1 is safer" + + assert autolink_deprecated(msg, current_module: AutolinkTest.Local) == + ~s|to_existing_atom/1 is safer| + + msg = "Use to_existing_atom/1, which is safer" + + assert autolink_deprecated(msg, current_module: AutolinkTest.Local) == + ~s|Use to_existing_atom/1, which is safer| + + msg = "Use to_existing_atom/1. May also use to_unsafe_atom/1" + + assert autolink_deprecated(msg, current_module: AutolinkTest.Local) == + ~s|Use to_existing_atom/1. May also use to_unsafe_atom/1| + end + + test "links remote functions" do + ExDoc.Refs.insert([ + {{:module, AutolinkTest.Remote}, :public}, + {{:function, AutolinkTest.Remote, :bar, 2}, :public}, + {{:module, AutolinkTest.Remote.Sub}, :public}, + {{:function, AutolinkTest.Remote.Sub, :lookup, 2}, :public} + ]) + + msg = "Use AutolinkTest.Remote.bar/2 instead" + + assert autolink_deprecated(msg) == + ~s|Use AutolinkTest.Remote.bar/2 instead| + + msg = "Use AutolinkTest.Remote.Sub.lookup/2 instead" + + assert autolink_deprecated(msg) == + ~s|Use AutolinkTest.Remote.Sub.lookup/2 instead| + end + + test "links erlang modules and functions" do + assert autolink_deprecated("Use :re.version/0 instead") == + ~s|Use :re.version/0 instead| + end + + test "links predicate and bang functions ending in ? or !" do + ExDoc.Refs.insert([ + {{:module, AutolinkTest.Pred}, :public}, + {{:function, AutolinkTest.Pred, :valid?, 1}, :public}, + {{:function, AutolinkTest.Pred, :action!, 1}, :public} + ]) + + assert autolink_deprecated("Use valid?/1 instead", current_module: AutolinkTest.Pred) == + ~s|Use valid?/1 instead| + + assert autolink_deprecated("Use action!/1 instead", current_module: AutolinkTest.Pred) == + ~s|Use action!/1 instead| + end + + test "does not link matches with surrounding word characters, colons, slashes, dots, or fragments" do + ExDoc.Refs.insert([ + {{:module, AutolinkTest.Edge}, :public}, + {{:function, AutolinkTest.Edge, :valid?, 1}, :public} + ]) + + assert autolink_deprecated("Use not_valid?/1 instead", current_module: AutolinkTest.Edge) == + "Use not_valid?/1 instead" + + assert autolink_deprecated("Use !valid?/1 instead", current_module: AutolinkTest.Edge) == + "Use !valid?/1 instead" + + assert autolink_deprecated("Use ::valid?/1 instead", current_module: AutolinkTest.Edge) == + "Use ::valid?/1 instead" + + msg = "See https://example.com/valid?/1" + assert autolink_deprecated(msg, current_module: AutolinkTest.Edge) == msg + + msg = "See https://example.com?valid?/1" + assert autolink_deprecated(msg, current_module: AutolinkTest.Edge) == msg + + msg = "See https://example.com#valid?/1" + assert autolink_deprecated(msg, current_module: AutolinkTest.Edge) == msg + + assert autolink_deprecated("See /path/to/valid?/1", current_module: AutolinkTest.Edge) == + "See /path/to/valid?/1" + + assert autolink_deprecated("See conn.valid?/1 instead", current_module: AutolinkTest.Edge) == + "See conn.valid?/1 instead" + + assert autolink_deprecated("See valid?/1/2 instead", current_module: AutolinkTest.Edge) == + "See valid?/1/2 instead" + + assert autolink_deprecated("See valid?/1#anchor instead", current_module: AutolinkTest.Edge) == + "See valid?/1#anchor instead" + + msg = "See conn.AutolinkTest.Edge.valid?/1 instead" + assert autolink_deprecated(msg, current_module: AutolinkTest.Edge) == msg + end + + test "does not link bare module names" do + ExDoc.Refs.insert([ + {{:module, AutolinkTestBare}, :public}, + {{:module, AutolinkTest.Nested}, :public} + ]) + + assert autolink_deprecated("Use AutolinkTestBare instead") == + "Use AutolinkTestBare instead" + + assert autolink_deprecated("Use AutolinkTest.Nested instead") == + "Use AutolinkTest.Nested instead" + end + + test "does not warn or raise on undefined or hidden functions" do + ExDoc.Refs.insert([ + {{:module, AutolinkTest.Undef}, :public}, + {{:function, AutolinkTest.Undef, :secret_fun, 1}, :hidden} + ]) + + msg = "Use AutolinkTest.Undef.secret_fun/1 or AutolinkTest.Undef.does_not_exist/1 instead" + assert autolink_deprecated(msg, warnings: :raise) == msg + end + + test "preserves plain text and escapes HTML without linkable targets" do + assert autolink_deprecated("Use <.link> instead") == "Use <.link> instead" + assert autolink_deprecated("Use something else instead") == "Use something else instead" + assert autolink_deprecated("Use unknown_func/1 instead") == "Use unknown_func/1 instead" + end + end + defmodule Elixir.InMemory do @callback hello() :: :world def hello(), do: :world @@ -779,4 +919,9 @@ defmodule ExDoc.Language.ElixirTest do config = struct!(ExDoc.Autolink, Keyword.merge(@default_options, options)) ExDoc.Language.Elixir.autolink_spec(spec, config) end + + defp autolink_deprecated(text, options \\ []) when is_binary(text) do + config = struct!(ExDoc.Autolink, Keyword.merge(@default_options, options)) + ExDoc.Language.Elixir.autolink_deprecated(text, config) + end end diff --git a/test/ex_doc/language/erlang_test.exs b/test/ex_doc/language/erlang_test.exs index 702793fe6..8b3b63122 100644 --- a/test/ex_doc/language/erlang_test.exs +++ b/test/ex_doc/language/erlang_test.exs @@ -877,6 +877,18 @@ defmodule ExDoc.Language.ErlangTest do end end + describe "autolink_deprecated/2" do + test "escapes HTML entities" do + assert autolink_deprecated("Use & \"bar\"") == + "Use <other> & "bar"" + end + + test "passes through plain text without autolinking" do + assert autolink_deprecated("Use foo/0 instead") == + "Use foo/0 instead" + end + end + defp autolink_spec(binary, _c, opts \\ []) when is_binary(binary) do config = opts @@ -950,6 +962,15 @@ defmodule ExDoc.Language.ErlangTest do |> ExDoc.DocAST.to_html() end + defp autolink_deprecated(text, opts \\ []) when is_binary(text) do + config = + opts + |> Keyword.put(:language, ExDoc.Language.Erlang) + |> then(&struct!(ExDoc.Autolink, &1)) + + ExDoc.Language.Erlang.autolink_deprecated(text, config) + end + defp warn(fun, md \\ []) when is_function(fun, 0) do fun.() assert_received {:warn, message, metadata} diff --git a/test/fixtures/deprecated.ex b/test/fixtures/deprecated.ex new file mode 100644 index 000000000..731389bae --- /dev/null +++ b/test/fixtures/deprecated.ex @@ -0,0 +1,19 @@ +defmodule Deprecated do + @moduledoc """ + A module for testing deprecations. + """ + @moduledoc deprecated: "Use example_1/0 or String.to_atom/1 instead" + + defmacro example_1, do: 1 + + @doc "A function with links in deprecation" + @deprecated "Use example_1/0 or String.to_atom/1 instead" + def example_with_links, do: :ok + + @doc "A function without links in deprecation" + @deprecated "Use something else instead" + def example_without_links, do: :ok + + @deprecated "Use example_1/0 or String.to_atom/1 instead" + def example_without_docs, do: nil +end