Skip to content

Warn when trying to reference types in hidden modules #1940

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

Merged
merged 2 commits into from
Aug 15, 2024
Merged

Warn when trying to reference types in hidden modules #1940

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c6a0a3f
Warn when trying to reference types in hidden modules
voughtdq Aug 12, 2024
d2257ba
Merge branch 'elixir-lang:main' into warn-on-hidden-type-from-hidden-…
voughtdq Aug 13, 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
25 changes: 25 additions & 0 deletions lib/ex_doc/autolink.ex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -511,6 +511,18 @@ defmodule ExDoc.Autolink do
(config.language != ExDoc.Language.Erlang or kind == :function) ->
nil

{:regular_link, :hidden, :hidden}
when not same_module? ->
if warn? do
maybe_warn(config, ref, :hidden, %{
original_text: original_text,
module_visibility: :hidden,
same_module?: false
})
end

nil

{_mode, _module_visibility, visibility} ->
if warn? do
maybe_warn(config, ref, visibility, %{original_text: original_text})
Expand Down Expand Up @@ -585,6 +597,19 @@ defmodule ExDoc.Autolink do
warn(config, message)
end

defp warn(
config,
{:type, module, _name, _arity},
:hidden,
%{original_text: original_text, module_visibility: :hidden, same_module?: false}
) do
message =
"documentation references type \"#{original_text}\" but the module " <>
"#{inspect(module)} is #{format_visibility(:hidden, :module)}"

warn(config, message)
end

defp warn(
config,
{kind, _module, _name, _arity},
Expand Down
10 changes: 9 additions & 1 deletion test/ex_doc/language/elixir_test.exs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -500,7 +500,9 @@ defmodule ExDoc.Language.ElixirTest do
ExDoc.Refs.insert([
{{:module, AutolinkTest.Foo}, :public},
{{:function, AutolinkTest.Foo, :bar, 1}, :hidden},
{{:type, AutolinkTest.Foo, :bad, 0}, :hidden}
{{:type, AutolinkTest.Foo, :bad, 0}, :hidden},
{{:module, AutoLinkTest.Hidden}, :hidden},
{{:type, AutoLinkTest.Hidden, :my_type, 0}, :hidden}
Copy link
Member

Choose a reason for hiding this comment

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

note to self: The testing setup is not fantastic. I don't know off the top of my head whether here :hidden is supposed to reflect the type is hidden or the type is (so to speak) public but because it is in hidden module it ends up hidden. This is an implementation detail.

A more robust way to test this would be more end-to-end:

image

])

opts = [
Expand All @@ -519,6 +521,12 @@ defmodule ExDoc.Language.ElixirTest do
assert message =~ ~s|references function "AutolinkTest.Foo.bar/1" but it is hidden|
assert metadata == [file: "foo.ex", line: 2]

assert warn(fn ->
assert autolink_doc("`t:AutoLinkTest.Hidden.my_type/0`", opts) ==
~s|<code class="inline">t:AutoLinkTest.Hidden.my_type/0</code>|
end) =~
~s|documentation references type "t:AutoLinkTest.Hidden.my_type/0" but the module AutoLinkTest.Hidden is hidden|

assert warn(fn ->
assert autolink_doc("`t:AutolinkTest.Foo.bad/0`", opts) ==
~s|<code class="inline">t:AutolinkTest.Foo.bad/0</code>|
Expand Down
Loading