Add test for warnings if referencing filtered typespec

[viniciusmuller]

No description provided.

[josevalim]

Assigning to @wojtekmach in case he knows a better way to write these tests.

[wojtekmach]

We want to get away from fixtures as these are hard to maintain. Some time ago we have introduced TestHelper.elixirc and .erlc functions to generate modules and docs "inline". We don't have to rewrite all tests but once we change existing or add new tests, ideally we'd move towards that.

My suggestion is to rewrite this test to something like the following:

  test "warns when referencing typespec on filtered module", context do
    TestHelper.elixirc(context, ~S'''
    defmodule FilteredOutModule do
      @type t() :: term()
    end

    defmodule PublicModule do
      @type t() :: FilteredOutModule.t()
    end
    ''')

    output =
      capture_io(:stderr, fn ->
        generate_docs(
          doc_config(context,
            source_beam: "#{context.tmp_dir}/ebin",
            filter_modules: ~r/PublicModule/
          )
        )
      end)

    assert output =~ "typespec references filtered module: FilteredOutModule.t()"
  end

btw, as I alluded to in the module name, I wonder if the warning should say:

typespec references filtered out module (...)
                             ^^^

but not sure, perhaps it's ok as is.

I believe I haven't considered filter_modules when redesigning autolink warnings. In other words, we shouldn't warn on just typespecs like in https://github.com/elixir-lang/ex_doc/pull/1761/files#diff-9fbe8daa2950d6163a320e9b4ce2b1667fab4185f4593dafb1f1bb672ddee0e1R793 but I believe we need a more general solution, to warn when referencing filtered out modules as well as their functions and callbacks. This should produce a warning but currently does not:

    TestHelper.elixirc(context, ~S'''
    defmodule FilteredOutModule do
      def foo do
      end
    end

    defmodule PublicModule do
      @moduledoc """
      See `FilteredOutModule.foo/0`.
      """
    end
    ''')

    output =
      capture_io(:stderr, fn ->
        generate_docs(
          doc_config(context,
            source_beam: "#{context.tmp_dir}/ebin",
            filter_modules: ~r/PublicModule/
          )
        )
      end)

We build a list of references and whether they are visible in the ExDoc.Autolink.Refs. I think when retriever parses the module from the current project it inserts its references into Refs. So that might be a good place to filter out things, mark the whole module as hidden and then I think referencing its functions, types, etc would warn.

[viniciusmuller]

Could we do something like setting the module visibility to :filtered and then show a "module filtered" message when we reference a filtered module, kinda like it's done currently for the hidden modules?

[wojtekmach]

sounds good to me

[wojtekmach]

@viniciusmuller I fixed this in 7fd5238 on main. I also added a follow-up PR with slightly different solution. Feel free to explore the :filtered visibility approach if you want!