Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Use Hexdocs format in :otp anchors #1908

Merged
merged 3 commits into from
May 29, 2024
Merged

Use Hexdocs format in :otp anchors #1908

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
0514aa3
use hexdocs format in :otp anchors
ruslandoga May 29, 2024
3c6b64e
update language/erlang tests
ruslandoga May 29, 2024
40ceabe
when erlang has docs, private types have links
ruslandoga May 29, 2024
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
20 changes: 6 additions & 14 deletions lib/ex_doc/autolink.ex
View file
Open in desktop
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
Open in desktop
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
Open in desktop
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>().|
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ https://www.erlang.org/doc/apps/erts/erlang.html#t:atom/0


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}.|
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ https://www.erlang.org/doc/man/uri_string.html#t:uri_string/0 redirects to https://www.erlang.org/doc/apps/stdlib/uri_string.html#t:uri_string/0

Copy link
Contributor Author

@ruslandoga ruslandoga May 29, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we update man links as well or is it OK to rely on www.erlang.org to always perform this redirect?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would say let's go ahead and link to the new page! Especially as I assume it will be less code? But we can do it in a next PR. :)

end

defp generate_docs(c) do
Expand Down
10 changes: 5 additions & 5 deletions test/ex_doc/language/elixir_test.exs
View file
Open in desktop
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>|
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ https://www.erlang.org/doc/apps/stdlib/lists.html#all/2

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>|
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ https://www.erlang.org/doc/apps/stdlib/gen_server.html#c:handle_call/3

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>|
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ https://www.erlang.org/doc/man/array.html#t:array/0 redirects to https://www.erlang.org/doc/apps/stdlib/array.html#t:array/0

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>|
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ https://www.erlang.org/doc/apps/stdlib/lists.html#all/2

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>()]
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ https://www.erlang.org/doc/man/sets.html#t:set/0 redirects to https://www.erlang.org/doc/apps/stdlib/sets.html#t:set/0

end

test "escape special HTML characters" do
Expand Down
38 changes: 19 additions & 19 deletions test/ex_doc/language/erlang_test.exs
View file
Open in desktop
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>|
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ https://www.erlang.org/doc/apps/stdlib/array.html#new/0

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>|
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ https://www.erlang.org/doc/apps/erts/zlib.html#gunzip/1

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>|
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ https://www.erlang.org/doc/apps/stdlib/array.html#t:array/0

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>|
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ https://www.erlang.org/doc/apps/erts/erlang.html#node/0

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>|
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ https://www.erlang.org/doc/apps/erts/erlang.html#t:integer/0

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>|
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ https://www.erlang.org/doc/apps/erts/erlang.html#t:nil/0

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>|
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ https://www.erlang.org/doc/apps/stdlib/lists.html#reverse/1

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>())| <>
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ https://www.erlang.org/doc/apps/erts/erlang.html#t:module/0

~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>()}]].|
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ https://www.erlang.org/doc/apps/erts/erlang.html#t:atom/0

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>()}.|
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ https://www.erlang.org/doc/apps/stdlib/sets.html#t:set/1

✅ https://www.erlang.org/doc/apps/erts/erlang.html#t:integer/0

✅ https://www.erlang.org/doc/apps/erts/erlang.html#t:float/0

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>().|
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ https://www.erlang.org/doc/apps/stdlib/sets.html#t:set/0

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
Open in desktop
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
Loading