diff --git a/lib/ex_doc/autolink.ex b/lib/ex_doc/autolink.ex index f5b2ed3fc..0c9b42ac0 100644 --- a/lib/ex_doc/autolink.ex +++ b/lib/ex_doc/autolink.ex @@ -24,7 +24,8 @@ defmodule ExDoc.Autolink do # # * `:extras` - map of extras # - # * `:skip_undefined_reference_warnings_on` - list of modules to skip the warning on + # * `:skip_undefined_reference_warnings_on` - function that will be called with + # a module/function/file/etc and return a boolean whether to skip warning on it. # # * `:skip_code_autolink_to` - function that will be called with a term and return a boolean # whether to skip autolinking to it. @@ -54,7 +55,7 @@ defmodule ExDoc.Autolink do ext: ".html", current_kfa: nil, siblings: [], - skip_undefined_reference_warnings_on: [], + skip_undefined_reference_warnings_on: &ExDoc.Config.skip_undefined_reference_warnings_on/1, skip_code_autolink_to: &ExDoc.Config.skip_code_autolink_to/1, force_module_prefix: nil, filtered_modules: [], @@ -165,10 +166,12 @@ defmodule ExDoc.Autolink do end def maybe_warn(config, ref, visibility, metadata) do - skipped = config.skip_undefined_reference_warnings_on file = Path.relative_to_cwd(config.file) - unless Enum.any?([config.id, config.module_id, file], &(&1 in skipped)) do + unless Enum.any?( + [config.id, config.module_id, file], + config.skip_undefined_reference_warnings_on + ) do warn(config, ref, visibility, metadata) end end diff --git a/lib/ex_doc/config.ex b/lib/ex_doc/config.ex index a71a18149..082526e03 100644 --- a/lib/ex_doc/config.ex +++ b/lib/ex_doc/config.ex @@ -8,6 +8,7 @@ defmodule ExDoc.Config do def before_closing_footer_tag(_), do: "" def before_closing_body_tag(_), do: "" def annotations_for_docs(_), do: [] + def skip_undefined_reference_warnings_on(_string), do: false def skip_code_autolink_to(_string), do: false defstruct annotations_for_docs: &__MODULE__.annotations_for_docs/1, @@ -39,7 +40,8 @@ defmodule ExDoc.Config do proglang: :elixir, project: nil, retriever: ExDoc.Retriever, - skip_undefined_reference_warnings_on: [], + skip_undefined_reference_warnings_on: + &__MODULE__.skip_undefined_reference_warnings_on/1, skip_code_autolink_to: &__MODULE__.skip_code_autolink_to/1, source_beam: nil, source_ref: @default_source_ref, @@ -77,7 +79,7 @@ defmodule ExDoc.Config do package: :atom | nil, project: nil | String.t(), retriever: atom(), - skip_undefined_reference_warnings_on: [String.t()], + skip_undefined_reference_warnings_on: (String.t() -> boolean), skip_code_autolink_to: (String.t() -> boolean), source_beam: nil | String.t(), source_ref: nil | String.t(), @@ -103,6 +105,13 @@ defmodule ExDoc.Config do options end + {skip_undefined_reference_warnings_on, options} = + Keyword.pop( + options, + :skip_undefined_reference_warnings_on, + &skip_undefined_reference_warnings_on/1 + ) + {skip_code_autolink_to, options} = Keyword.pop(options, :skip_code_autolink_to, &skip_code_autolink_to/1) @@ -120,7 +129,9 @@ defmodule ExDoc.Config do output: normalize_output(output), proglang: normalize_proglang(proglang), project: project, - skip_code_autolink_to: normalize_skip_code_autolink_to(skip_code_autolink_to), + skip_undefined_reference_warnings_on: + normalize_skip_list_function(skip_undefined_reference_warnings_on), + skip_code_autolink_to: normalize_skip_list_function(skip_code_autolink_to), source_url_pattern: source_url_pattern, version: vsn } @@ -174,10 +185,10 @@ defmodule ExDoc.Config do defp normalize_filter_modules(fun) when is_function(fun, 2), do: fun - defp normalize_skip_code_autolink_to(strings) when is_list(strings), + defp normalize_skip_list_function(strings) when is_list(strings), do: &(&1 in strings) - defp normalize_skip_code_autolink_to(fun) when is_function(fun, 1), + defp normalize_skip_list_function(fun) when is_function(fun, 1), do: fun defp guess_url(url, ref) do diff --git a/lib/mix/tasks/docs.ex b/lib/mix/tasks/docs.ex index f6ac79c4a..47069ff6f 100644 --- a/lib/mix/tasks/docs.ex +++ b/lib/mix/tasks/docs.ex @@ -153,12 +153,14 @@ defmodule Mix.Tasks.Docs do * `:skip_undefined_reference_warnings_on` - ExDoc warns when it can't create a `Mod.fun/arity` reference in the current project docs e.g. because of a typo. This list controls where to skip the warnings, for a given module/function/callback/type (e.g.: `["Foo", "Bar.baz/0"]`) - or on a given file (e.g.: `["pages/deprecations.md"]`); default: `[]`. + or on a given file (e.g.: `["pages/deprecations.md"]`). This option can also be a function + from a reference string to a boolean (e.g.: `&String.match?(&1, ~r/Foo/)`); + default is nothing to be skipped. * `:skip_code_autolink_to` - Similar to `:skip_undefined_reference_warnings_on`, this option controls which terms will be skipped by ExDoc when building documentation. Useful for example if you want to highlight private modules or functions without warnings. - This option can be a function from a term to a boolean (e.g.: `&String.match?(&1, ~r/PrivateModule/)` + This option can be a function from a term to a boolean (e.g.: `&String.match?(&1, ~r/PrivateModule/)`) or a list of terms (e.g.:`["PrivateModule", "PrivateModule.func/1"]`); default is nothing to be skipped. diff --git a/test/ex_doc/config_test.exs b/test/ex_doc/config_test.exs index 9b00ddb1b..fd348284c 100644 --- a/test/ex_doc/config_test.exs +++ b/test/ex_doc/config_test.exs @@ -31,6 +31,26 @@ defmodule ExDoc.ConfigTest do refute config.filter_modules.(Foo, %{works: false}) end + test "normalizes skip_undefined_reference_warnings_on" do + config = + ExDoc.Config.build(@project, @version, + skip_undefined_reference_warnings_on: ["Foo", "Bar.baz/0"] + ) + + assert config.skip_undefined_reference_warnings_on.("Foo") + assert config.skip_undefined_reference_warnings_on.("Bar.baz/0") + refute config.skip_undefined_reference_warnings_on.("Foo.bar/1") + + config = + ExDoc.Config.build(@project, @version, + skip_undefined_reference_warnings_on: &String.match?(&1, ~r/Foo/) + ) + + assert config.skip_undefined_reference_warnings_on.("Foo") + refute config.skip_undefined_reference_warnings_on.("Bar.baz/0") + assert config.skip_undefined_reference_warnings_on.("Foo.bar/1") + end + test "normalizes skip_code_autolink_to" do config = ExDoc.Config.build(@project, @version, diff --git a/test/ex_doc/language/elixir_test.exs b/test/ex_doc/language/elixir_test.exs index 109dbf32f..f1b24b3a8 100644 --- a/test/ex_doc/language/elixir_test.exs +++ b/test/ex_doc/language/elixir_test.exs @@ -668,7 +668,7 @@ defmodule ExDoc.Language.ElixirTest do opts = [ warnings: :send, - skip_undefined_reference_warnings_on: ["MyModule"], + skip_undefined_reference_warnings_on: &(&1 in ["MyModule"]), module_id: "MyModule" ]