Ex_doc: Linking to function starting with underscore gets links but docs do not exist

[eksperimental]

defmodule Foo do
  @moduledoc """
  `_foo/1`
  """

  def _foo(foo) do
    foo
  end
end

The module docs will link to _foo, but _foo will not show in the generated docs.
A real case happens when you locally link to __using__/1

[josevalim]

Don’t we warn if you link to something without docs?

[eksperimental]

Here' s a more complete example

defmodule Foo do
  @moduledoc """
  `_foo/1`, `Foo._foo/1`, `boo/1`, `Foo.boo/1`
  """

  def _foo(foo) do
    foo
  end
end

$ mix docs
Generating docs...
warning: documentation references "Foo.boo/1" but it is undefined or private
  lib/foo.ex:2: Foo

View "html" docs at "doc/index.html"
warning: documentation references "Foo.boo/1" but it is undefined or private
  lib/foo.ex:2: Foo

View "epub" docs at "doc/buildable.epub"



md5-2430234b4d163f729ddfc06593b6e6e5



 Foo

_foo/1, Foo._foo/1, boo/1, Foo.boo/1

[jonatanklosko]

As far as I understand, the problem comes from the fact that underscored functions get :public visibility in the ExDoc.Refs cache, but they are ignored when generating docs.

---

Autolinking relies on the visibility stored in the ExDoc.Refs cache:

https://github.com/elixir-lang/ex_doc/blob/15560a59f39d3d6917ee5070adc121a00f1814db/lib/ex_doc/autolink.ex#L476-L480

This visibility is computed here:

https://github.com/elixir-lang/ex_doc/blob/15560a59f39d3d6917ee5070adc121a00f1814db/lib/ex_doc/refs.ex#L107-L110

https://github.com/elixir-lang/ex_doc/blob/15560a59f39d3d6917ee5070adc121a00f1814db/lib/ex_doc/refs.ex#L135-L136

So unless the doc is explicitly hidden we assign :public visibility.

---

On the other hand, when generating docs there are more specific criteria a function needs to satisfy:

https://github.com/elixir-lang/ex_doc/blob/15560a59f39d3d6917ee5070adc121a00f1814db/lib/ex_doc/retriever.ex#L262-L267

This causes a discrepancy, where some refs are ignored, yet they are marked :public in the cache.

---

One solution would be to determine the visibility using the same rules as for doc? (in which case it would be better to extract it somewhere).

[eksperimental]

As far as I understand, the problem comes from the fact that underscored functions get :public visibility in the ExDoc.Refs cache, but they are ignored when generating docs.

Autolinking relies on the visibility stored in the ExDoc.Refs cache:

https://github.com/elixir-lang/ex_doc/blob/15560a59f39d3d6917ee5070adc121a00f1814db/lib/ex_doc/autolink.ex#L476-L480

This visibility is computed here:

https://github.com/elixir-lang/ex_doc/blob/15560a59f39d3d6917ee5070adc121a00f1814db/lib/ex_doc/refs.ex#L107-L110

https://github.com/elixir-lang/ex_doc/blob/15560a59f39d3d6917ee5070adc121a00f1814db/lib/ex_doc/refs.ex#L135-L136

So unless the doc is explicitly hidden we assign :public visibility.

On the other hand, when generating docs there are more specific criteria a function needs to satisfy:

https://github.com/elixir-lang/ex_doc/blob/15560a59f39d3d6917ee5070adc121a00f1814db/lib/ex_doc/retriever.ex#L262-L267

This causes a discrepancy, where some refs are ignored, yet they are marked :public in the cache.

One solution would be to determine the visibility using the same rules as for doc? (in which case it would be better to extract it somewhere).

Thank you @jonatanklosko, this is the way to go. I already have a working fix for this. I will upload it soon.