Make a function acceptable for :skip_undefined_reference_warnings_on …

…option (#1879)

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

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

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.
 

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,

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"
     ]