Skip to content

Commit

Permalink
Use Hexdocs format in :otp anchors (#1908)
Browse files Browse the repository at this point in the history
  • Loading branch information
@ruslandoga
ruslandoga committed May 29, 2024
1 parent f4a46cb commit 2f23a05
Show file tree
Hide file tree
Showing 6 changed files with 37 additions and 45 deletions.
20 changes: 6 additions & 14 deletions lib/ex_doc/autolink.ex
View file
Original file line number Diff line number Diff line change
Expand Up @@ -430,7 +430,7 @@ defmodule ExDoc.Autolink do

case {kind, visibility} do
{_kind, :public} ->
fragment(tool(module, config), kind, name, arity)
fragment(kind, name, arity)

{:function, _visibility} ->
case config.language.try_autoimported_function(name, arity, mode, config, original_text) do
Expand Down Expand Up @@ -464,22 +464,14 @@ defmodule ExDoc.Autolink do
end
end

def fragment(tool, kind, nil, arity) do
fragment(tool, kind, "nil", arity)
def fragment(kind, nil, arity) do
fragment(kind, "nil", arity)
end

def fragment(:ex_doc, kind, name, arity) do
def fragment(kind, name, arity) do
"#" <> prefix(kind) <> "#{encode_fragment_name(name)}/#{arity}"
end

def fragment(:otp, kind, name, arity) do
case kind do
:function -> "##{encode_fragment_name(name)}-#{arity}"
:callback -> "#Module:#{encode_fragment_name(name)}-#{arity}"
:type -> "#type-#{encode_fragment_name(name)}"
end
end

defp encode_fragment_name(name) when is_atom(name) do
encode_fragment_name(Atom.to_string(name))
end
Expand All @@ -503,10 +495,10 @@ defmodule ExDoc.Autolink do
tool = tool(module, config)

if same_module? do
fragment(tool, kind, name, arity)
fragment(kind, name, arity)
else
url = string_app_module_url(original_text, tool, module, nil, config)
url && url <> fragment(tool, kind, name, arity)
url && url <> fragment(kind, name, arity)
end

{:regular_link, module_visibility, :undefined}
Expand Down
4 changes: 2 additions & 2 deletions lib/ex_doc/language/erlang.ex
View file
Original file line number Diff line number Diff line change
Expand Up @@ -431,12 +431,12 @@ defmodule ExDoc.Language.Erlang do
end

defp final_url({kind, name, arity}, _config) do
Autolink.fragment(:ex_doc, kind, name, arity)
Autolink.fragment(kind, name, arity)
end

defp final_url({kind, module, name, arity}, config) do
tool = Autolink.tool(module, config)
Autolink.app_module_url(tool, module, Autolink.fragment(tool, kind, name, arity), config)
Autolink.app_module_url(tool, module, Autolink.fragment(kind, name, arity), config)
end

@impl true
Expand Down
4 changes: 2 additions & 2 deletions test/ex_doc/formatter/html/erlang_test.exs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -36,10 +36,10 @@ defmodule ExDoc.Formatter.HTML.ErlangTest do
~s|-spec</span> foo(<a href=\"#t:t/0\">t</a>()) -&gt; <a href=\"#t:t/0\">t</a>().|

assert html =~
~s|-type</span> t() :: <a href=\"https://www.erlang.org/doc/man/erlang.html#type-atom\">atom</a>().|
~s|-type</span> t() :: <a href=\"https://www.erlang.org/doc/man/erlang.html#t:atom/0\">atom</a>().|

assert html =~
~s|-type</span> t2() :: #rec{k1 :: <a href=\"https://www.erlang.org/doc/man/uri_string.html#type-uri_string\">uri_string:uri_string</a>(), k2 :: <a href=\"https://www.erlang.org/doc/man/uri_string.html#type-uri_string\">uri_string:uri_string</a>() \| undefined}.|
~s|-type</span> t2() :: #rec{k1 :: <a href=\"https://www.erlang.org/doc/man/uri_string.html#t:uri_string/0\">uri_string:uri_string</a>(), k2 :: <a href=\"https://www.erlang.org/doc/man/uri_string.html#t:uri_string/0\">uri_string:uri_string</a>() \| undefined}.|
end

defp generate_docs(c) do
Expand Down
10 changes: 5 additions & 5 deletions test/ex_doc/language/elixir_test.exs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -99,7 +99,7 @@ defmodule ExDoc.Language.ElixirTest do

test "erlang stdlib function" do
assert autolink_doc("`:lists.all/2`") ==
~s|<a href="https://www.erlang.org/doc/man/lists.html#all-2"><code class="inline">:lists.all/2</code></a>|
~s|<a href="https://www.erlang.org/doc/man/lists.html#all/2"><code class="inline">:lists.all/2</code></a>|
end

test "local function" do
Expand Down Expand Up @@ -150,7 +150,7 @@ defmodule ExDoc.Language.ElixirTest do

test "erlang callback" do
assert autolink_doc("`c::gen_server.handle_call/3`") ==
~s|<a href="https://www.erlang.org/doc/man/gen_server.html#Module:handle_call-3"><code class="inline">:gen_server.handle_call/3</code></a>|
~s|<a href="https://www.erlang.org/doc/man/gen_server.html#c:handle_call/3"><code class="inline">:gen_server.handle_call/3</code></a>|
end

test "elixir type" do
Expand All @@ -171,7 +171,7 @@ defmodule ExDoc.Language.ElixirTest do

test "erlang type" do
assert autolink_doc("`t::array.array/0`") ==
~s|<a href="https://www.erlang.org/doc/man/array.html#type-array"><code class="inline">:array.array/0</code></a>|
~s|<a href="https://www.erlang.org/doc/man/array.html#t:array/0"><code class="inline">:array.array/0</code></a>|
end

test "special forms" do
Expand Down Expand Up @@ -207,7 +207,7 @@ defmodule ExDoc.Language.ElixirTest do
~s|<a href="https://www.erlang.org/doc/man/lists.html">custom text</a>|

assert autolink_doc("[custom text](`:lists.all/2`)") ==
~s|<a href="https://www.erlang.org/doc/man/lists.html#all-2">custom text</a>|
~s|<a href="https://www.erlang.org/doc/man/lists.html#all/2">custom text</a>|
end

test "mix task" do
Expand Down Expand Up @@ -450,7 +450,7 @@ defmodule ExDoc.Language.ElixirTest do

test "Erlang stdlib types" do
assert autolink_spec(quote(do: t() :: :sets.set())) ==
~s[t() :: <a href="https://www.erlang.org/doc/man/sets.html#type-set">:sets.set</a>()]
~s[t() :: <a href="https://www.erlang.org/doc/man/sets.html#t:set/0">:sets.set</a>()]
end

test "escape special HTML characters" do
Expand Down
38 changes: 19 additions & 19 deletions test/ex_doc/language/erlang_test.exs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -84,7 +84,7 @@ defmodule ExDoc.Language.ErlangTest do

test "OTP function", c do
assert autolink_edoc("{@link array:new/0}", c) ==
~s|<a href="https://www.erlang.org/doc/man/array.html#new-0"><code>array:new/0</code></a>|
~s|<a href="https://www.erlang.org/doc/man/array.html#new/0"><code>array:new/0</code></a>|
end

test "OTP function when generating OTP docs", c do
Expand All @@ -99,12 +99,12 @@ defmodule ExDoc.Language.ErlangTest do

test "ERTS function", c do
assert autolink_edoc("{@link zlib:gunzip/1}", c) ==
~s|<a href="https://www.erlang.org/doc/man/zlib.html#gunzip-1"><code>zlib:gunzip/1</code></a>|
~s|<a href="https://www.erlang.org/doc/man/zlib.html#gunzip/1"><code>zlib:gunzip/1</code></a>|
end

test "app function", c do
assert autolink_edoc("{@link //stdlib/array:new/0}", c) ==
~s|<a href="https://www.erlang.org/doc/man/array.html#new-0"><code>array:new/0</code></a>|
~s|<a href="https://www.erlang.org/doc/man/array.html#new/0"><code>array:new/0</code></a>|
end

test "external function", c do
Expand All @@ -124,12 +124,12 @@ defmodule ExDoc.Language.ErlangTest do

test "OTP type", c do
assert autolink_edoc("{@link array:array()}", c) ==
~s|<a href="https://www.erlang.org/doc/man/array.html#type-array"><code>array:array()</code></a>|
~s|<a href="https://www.erlang.org/doc/man/array.html#t:array/0"><code>array:array()</code></a>|
end

test "app type", c do
assert autolink_edoc("{@link //stdlib/array:array()}", c) ==
~s|<a href="https://www.erlang.org/doc/man/array.html#type-array"><code>array:array()</code></a>|
~s|<a href="https://www.erlang.org/doc/man/array.html#t:array/0"><code>array:array()</code></a>|
end

@myList (if :erlang.system_info(:otp_release) >= ~c"27" do
Expand Down Expand Up @@ -310,7 +310,7 @@ defmodule ExDoc.Language.ErlangTest do

test "function in module autoimport using slash", c do
assert autolink_doc("`node/0`", c) ==
~s|<a href="https://www.erlang.org/doc/man/erlang.html#node-0"><code class="inline">node/0</code></a>|
~s|<a href="https://www.erlang.org/doc/man/erlang.html#node/0"><code class="inline">node/0</code></a>|
end

test "type in module autoimport", c do
Expand All @@ -320,7 +320,7 @@ defmodule ExDoc.Language.ErlangTest do

test "type in module autoimport using slash", c do
assert autolink_doc("`t:integer/0`", c) ==
~s|<a href="https://www.erlang.org/doc/man/erlang.html#type-integer"><code class="inline">integer/0</code></a>|
~s|<a href="https://www.erlang.org/doc/man/erlang.html#t:integer/0"><code class="inline">integer/0</code></a>|
end

test "bad function in module code", c do
Expand All @@ -335,7 +335,7 @@ defmodule ExDoc.Language.ErlangTest do

test "linking to auto-imported nil works", c do
assert autolink_doc("[`[]`](`t:nil/0`)", c) ==
~s|<a href="https://www.erlang.org/doc/man/erlang.html#type-nil"><code class="inline">[]</code></a>|
~s|<a href="https://www.erlang.org/doc/man/erlang.html#t:nil/0"><code class="inline">[]</code></a>|
end

test "linking to local nil works", c do
Expand Down Expand Up @@ -543,7 +543,7 @@ defmodule ExDoc.Language.ErlangTest do

test "OTP function", c do
assert autolink_extra("`lists:reverse/1`", c) ==
~s|<a href="https://www.erlang.org/doc/man/lists.html#reverse-1"><code class="inline">lists:reverse/1</code></a>|
~s|<a href="https://www.erlang.org/doc/man/lists.html#reverse/1"><code class="inline">lists:reverse/1</code></a>|
end

test "type", c do
Expand All @@ -553,7 +553,7 @@ defmodule ExDoc.Language.ErlangTest do

test "OTP type", c do
assert autolink_extra("`t:array:array/0`", c) ==
~s|<a href="https://www.erlang.org/doc/man/array.html#type-array"><code class="inline">array:array/0</code></a>|
~s|<a href="https://www.erlang.org/doc/man/array.html#t:array/0"><code class="inline">array:array/0</code></a>|
end

test "module", c do
Expand Down Expand Up @@ -684,9 +684,9 @@ defmodule ExDoc.Language.ErlangTest do

test "spec when fun is called record", c do
assert autolink_spec("-spec record(module()) -> [[{module(), atom()}]].", c) ==
~s|record(<a href="https://www.erlang.org/doc/man/erlang.html#type-module">module</a>())| <>
~s| -> [[{<a href="https://www.erlang.org/doc/man/erlang.html#type-module">module</a>(),| <>
~s| <a href="https://www.erlang.org/doc/man/erlang.html#type-atom">atom</a>()}]].|
~s|record(<a href="https://www.erlang.org/doc/man/erlang.html#t:module/0">module</a>())| <>
~s| -> [[{<a href="https://www.erlang.org/doc/man/erlang.html#t:module/0">module</a>(),| <>
~s| <a href="https://www.erlang.org/doc/man/erlang.html#t:atom/0">atom</a>()}]].|
end

test "callback", c do
Expand Down Expand Up @@ -724,7 +724,7 @@ defmodule ExDoc.Language.ErlangTest do
~S"-spec foo() -> #{atom() := sets:set(integer()), float() => t()}.",
c
) ==
~S|foo() -> #{<a href="https://www.erlang.org/doc/man/erlang.html#type-atom">atom</a>() := <a href="https://www.erlang.org/doc/man/sets.html#type-set">sets:set</a>(<a href="https://www.erlang.org/doc/man/erlang.html#type-integer">integer</a>()), <a href="https://www.erlang.org/doc/man/erlang.html#type-float">float</a>() => <a href="#t:t/0">t</a>()}.|
~S|foo() -> #{<a href="https://www.erlang.org/doc/man/erlang.html#t:atom/0">atom</a>() := <a href="https://www.erlang.org/doc/man/sets.html#t:set/1">sets:set</a>(<a href="https://www.erlang.org/doc/man/erlang.html#t:integer/0">integer</a>()), <a href="https://www.erlang.org/doc/man/erlang.html#t:float/0">float</a>() => <a href="#t:t/0">t</a>()}.|
end

test "vars", c do
Expand All @@ -744,12 +744,12 @@ defmodule ExDoc.Language.ErlangTest do

test "record - one field", c do
assert autolink_spec(~s"-spec foo() -> #x{x :: atom()} | t().", c) ==
~s[foo() -> #x{x :: <a href="https://www.erlang.org/doc/man/erlang.html#type-atom">atom</a>()} | <a href="#t:t/0">t</a>().]
~s[foo() -> #x{x :: <a href="https://www.erlang.org/doc/man/erlang.html#t:atom/0">atom</a>()} | <a href="#t:t/0">t</a>().]
end

test "record - two fields", c do
assert autolink_spec(~s"-spec foo() -> #x{x :: atom(), y :: sets:set(integer())} | t().", c) ==
~s[foo() -> #x{x :: <a href="https://www.erlang.org/doc/man/erlang.html#type-atom">atom</a>(), y :: <a href="https://www.erlang.org/doc/man/sets.html#type-set">sets:set</a>(<a href="https://www.erlang.org/doc/man/erlang.html#type-integer">integer</a>())} | <a href="#t:t/0">t</a>().]
~s[foo() -> #x{x :: <a href="https://www.erlang.org/doc/man/erlang.html#t:atom/0">atom</a>(), y :: <a href="https://www.erlang.org/doc/man/sets.html#t:set/1">sets:set</a>(<a href="https://www.erlang.org/doc/man/erlang.html#t:integer/0">integer</a>())} | <a href="#t:t/0">t</a>().]
end

test "record - two fields, known types", c do
Expand Down Expand Up @@ -789,12 +789,12 @@ defmodule ExDoc.Language.ErlangTest do

test "OTP type", c do
assert autolink_spec(~S"-spec foo() -> sets:set().", c) ==
~s|foo() -> <a href="https://www.erlang.org/doc/man/sets.html#type-set">sets:set</a>().|
~s|foo() -> <a href="https://www.erlang.org/doc/man/sets.html#t:set/0">sets:set</a>().|
end

test "OTP private type", c do
assert autolink_spec(~S"-spec foo() -> array:array_indx().", c) ==
~s|foo() -> <a href="https://www.erlang.org/doc/man/array.html#type-array_indx">array:array_indx</a>().|
~s|foo() -> <a href="https://www.erlang.org/doc/man/array.html#t:array_indx/0">array:array_indx</a>().|
end

test "skip typespec name", c do
Expand All @@ -820,7 +820,7 @@ defmodule ExDoc.Language.ErlangTest do
test "bad remote type", c do
assert warn(fn ->
assert autolink_spec(~S"-spec foo() -> bad:bad(atom()).", c, warnings: :send) ==
~s|foo() -> bad:bad(<a href="https://www.erlang.org/doc/man/erlang.html#type-atom">atom</a>()).|
~s|foo() -> bad:bad(<a href="https://www.erlang.org/doc/man/erlang.html#t:atom/0">atom</a>()).|
end) =~ ~s|references type "bad:bad/1" but it is undefined or private|
end
end
Expand Down
6 changes: 3 additions & 3 deletions test/ex_doc/retriever/erlang_test.exs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -415,7 +415,7 @@ defmodule ExDoc.Retriever.ErlangTest do
assert DocAST.to_string(function1.doc) =~ "function1/0 docs."

assert Erlang.autolink_spec(hd(function1.specs), current_kfa: {:function, :function1, 0}) ==
"function1() -> <a href=\"https://www.erlang.org/doc/man/erlang.html#type-atom\">atom</a>()."
"function1() -> <a href=\"https://www.erlang.org/doc/man/erlang.html#t:atom/0\">atom</a>()."

%ExDoc.FunctionNode{
id: "function2/0"
Expand Down Expand Up @@ -463,7 +463,7 @@ defmodule ExDoc.Retriever.ErlangTest do
assert Path.basename(callback1.source_url) == "mod.erl:4"

assert Erlang.autolink_spec(hd(callback1.specs), current_kfa: {:callback, :callback1, 0}) ==
"callback1() -> <a href=\"https://www.erlang.org/doc/man/erlang.html#type-atom\">atom</a>()."
"callback1() -> <a href=\"https://www.erlang.org/doc/man/erlang.html#t:atom/0\">atom</a>()."

assert optional_callback1.id == "c:optional_callback1/0"
assert optional_callback1.type == :callback
Expand Down Expand Up @@ -501,7 +501,7 @@ defmodule ExDoc.Retriever.ErlangTest do
assert type1.doc |> DocAST.to_string() =~ "type1/0 docs."

assert type1.spec |> Erlang.autolink_spec(current_kfa: {:type, :type1, 0}) ==
"type1() :: <a href=\"https://www.erlang.org/doc/man/erlang.html#type-atom\">atom</a>()."
"type1() :: <a href=\"https://www.erlang.org/doc/man/erlang.html#t:atom/0\">atom</a>()."
end
end
end

0 comments on commit 2f23a05

Please sign in to comment.