Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 11 additions & 1 deletion lib/ex_doc/formatter.ex
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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
Expand Down
4 changes: 2 additions & 2 deletions lib/ex_doc/formatter/epub/templates/module_template.eex
Original file line number Diff line number Diff line change
Expand Up @@ -3,9 +3,9 @@
<%= H.breakable_module_title(module.title) %> <%= H.module_type(module) %>
</h1>

<%= if deprecated = module.deprecated do %>
<%= if deprecated = module.deprecated_doc do %>
<div class="deprecated">
This <%= module.type %> is deprecated. <%=h deprecated %>.
This <%= module.type %> is deprecated. <%= deprecated %>.
</div>
<% end %>

Expand Down
4 changes: 2 additions & 2 deletions lib/ex_doc/formatter/html/templates/detail_template.eex
Original file line number Diff line number Diff line change
Expand Up @@ -18,9 +18,9 @@
<% end %>
</div>
</div>
<%= if deprecated = node.deprecated do %>
<%= if deprecated = node.deprecated_doc do %>
<div class="deprecated">
This <%= node.type %> is deprecated. <%= h(deprecated) %>.
This <%= node.type %> is deprecated. <%= deprecated %>.
</div>
<% end %>

Expand Down
4 changes: 2 additions & 2 deletions lib/ex_doc/formatter/html/templates/module_template.eex
Original file line number Diff line number Diff line change
Expand Up @@ -21,9 +21,9 @@
<% end %>
</div>

<%= if deprecated = module.deprecated do %>
<%= if deprecated = module.deprecated_doc do %>
<div class="deprecated">
This <%= module.type %> is deprecated. <%= h(deprecated) %>.
This <%= module.type %> is deprecated. <%= deprecated %>.
</div>
<% end %>

Expand Down
5 changes: 5 additions & 0 deletions lib/ex_doc/language.ex
Original file line number Diff line number Diff line change
Expand Up @@ -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.
"""
Expand Down
51 changes: 51 additions & 0 deletions lib/ex_doc/language/elixir.ex
Original file line number Diff line number Diff line change
Expand Up @@ -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
( # <reference>
(?:
(?:
:[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
) # </reference>
(?=[\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|<a href="#{url}"><code class="inline">#{ref}</code></a>|

_ ->
ref
end
end)
end

@impl true
def format_spec(ast) do
ast
Expand Down
5 changes: 5 additions & 0 deletions lib/ex_doc/language/erlang.ex
Original file line number Diff line number Diff line change
Expand Up @@ -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} =
Expand Down
4 changes: 4 additions & 0 deletions lib/ex_doc/nodes.ex
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand All @@ -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,
Expand All @@ -59,6 +61,7 @@ defmodule ExDoc.DocNode do
arity: 0,
defaults: [],
deprecated: nil,
deprecated_doc: nil,
doc: nil,
source_doc: nil,
type: nil,
Expand All @@ -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(),
Expand Down
13 changes: 13 additions & 0 deletions test/ex_doc/formatter/epub/templates_test.exs
Original file line number Diff line number Diff line change
Expand Up @@ -234,6 +234,19 @@ defmodule ExDoc.Formatter.EPUB.TemplatesTest do
assert content =~ "<p>A content example.</p>"
end

test "autolinks deprecation information" do
content = get_module_template([Deprecated])

assert content =~
~r{<div class="deprecated">\s*This module is deprecated. Use <a href="#example_1/0"><code class="inline">example_1/0</code></a> or <a href="https://elixir.hexdocs.pm/String.html#to_atom/1"><code class="inline">String.to_atom/1</code></a> instead.}

assert content =~
~r{<div class="deprecated">\s*This function is deprecated. Use something else instead.}

assert content =~
~r{<div class="deprecated">\s*This function is deprecated. Use <a href="#example_1/0"><code class="inline">example_1/0</code></a> or <a href="https://elixir.hexdocs.pm/String.html#to_atom/1"><code class="inline">String.to_atom/1</code></a> instead.}
end

test "outputs summaries" do
content = get_module_template([CompiledWithDocs])

Expand Down
21 changes: 21 additions & 0 deletions test/ex_doc/formatter/html/templates_test.exs
Original file line number Diff line number Diff line change
Expand Up @@ -478,6 +478,27 @@ defmodule ExDoc.Formatter.HTML.TemplatesTest do
~r{<div class="deprecated">\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{<span class="deprecated" title="Use something else instead">deprecated</span>}

assert content =~
~s{<span class="deprecated" title="Use example_1/0 or String.to_atom/1 instead">deprecated</span>}

refute content =~ ~s{title="Use <a href}

assert content =~
~r{<div class="deprecated">\s*This module is deprecated. Use <a href="#example_1/0"><code class="inline">example_1/0</code></a> or <a href="https://elixir.hexdocs.pm/String.html#to_atom/1"><code class="inline">String.to_atom/1</code></a> instead.}

assert content =~
~r{<div class="deprecated">\s*This function is deprecated. Use something else instead.}

assert content =~
~r{<div class="deprecated">\s*This function is deprecated. Use <a href="#example_1/0"><code class="inline">example_1/0</code></a> or <a href="https://elixir.hexdocs.pm/String.html#to_atom/1"><code class="inline">String.to_atom/1</code></a> instead.}
end

test "outputs the types and function specs", context do
content = get_module_template([TypesAndSpecs, TypesAndSpecs.Sub], context)
integer = ~s[<a href="https://elixir.hexdocs.pm/typespecs.html#basic-types">integer</a>()]
Expand Down
1 change: 1 addition & 0 deletions test/ex_doc/formatter/html_test.exs
Original file line number Diff line number Diff line change
Expand Up @@ -98,6 +98,7 @@ defmodule ExDoc.Formatter.HTMLTest do
%{"id" => "OverlappingDefaults"},
%{"id" => "TypesAndSpecs"},
%{"id" => "TypesAndSpecs.Sub"},
%{"id" => "Deprecated"},
%{"id" => "Warnings"},
%{"id" => "RandomError"}
],
Expand Down
2 changes: 2 additions & 0 deletions test/ex_doc/formatter/markdown_test.exs
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
145 changes: 145 additions & 0 deletions test/ex_doc/language/elixir_test.exs
Original file line number Diff line number Diff line change
Expand Up @@ -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 <a href="#to_existing_atom/1"><code class="inline">to_existing_atom/1</code></a> or <a href="#to_unsafe_atom/1"><code class="inline">to_unsafe_atom/1</code></a> instead|

assert autolink_deprecated("Use to_existing_atom/1.", current_module: AutolinkTest.Local) ==
~s|Use <a href="#to_existing_atom/1"><code class="inline">to_existing_atom/1</code></a>.|

msg = "to_existing_atom/1 is safer"

assert autolink_deprecated(msg, current_module: AutolinkTest.Local) ==
~s|<a href="#to_existing_atom/1"><code class="inline">to_existing_atom/1</code></a> is safer|

msg = "Use to_existing_atom/1, which is safer"

assert autolink_deprecated(msg, current_module: AutolinkTest.Local) ==
~s|Use <a href="#to_existing_atom/1"><code class="inline">to_existing_atom/1</code></a>, 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 <a href="#to_existing_atom/1"><code class="inline">to_existing_atom/1</code></a>. May also use <a href="#to_unsafe_atom/1"><code class="inline">to_unsafe_atom/1</code></a>|
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 <a href="AutolinkTest.Remote.html#bar/2"><code class="inline">AutolinkTest.Remote.bar/2</code></a> instead|

msg = "Use AutolinkTest.Remote.Sub.lookup/2 instead"

assert autolink_deprecated(msg) ==
~s|Use <a href="AutolinkTest.Remote.Sub.html#lookup/2"><code class="inline">AutolinkTest.Remote.Sub.lookup/2</code></a> instead|
end

test "links erlang modules and functions" do
assert autolink_deprecated("Use :re.version/0 instead") ==
~s|Use <a href="https://www.erlang.org/doc/apps/stdlib/re.html#version/0"><code class="inline">:re.version/0</code></a> 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 <a href="#valid?/1"><code class="inline">valid?/1</code></a> instead|

assert autolink_deprecated("Use action!/1 instead", current_module: AutolinkTest.Pred) ==
~s|Use <a href="#action!/1"><code class="inline">action!/1</code></a> 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 &lt;.link&gt; 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
Expand Down Expand Up @@ -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
Loading
Loading