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 %>
#{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{example_1/0 or String.to_atom/1 instead.}
+
+ assert content =~
+ ~r{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{example_1/0 or String.to_atom/1 instead.}
+
+ assert content =~
+ ~r{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