BartOtten
Warning: documentation references type "Phoenix.Router.Route.t()" but the module Phoenix.Router.Route is hidden
Problem
In one of my libs I add type information such as @type routes :: [Phoenix.Router.Route.t()]
This causes mix docs to throw warnings as the module (not the type) is hidden via @moduledoc false
warning: documentation references type "Phoenix.Router.Route.t()" but the module Phoenix.Router.Route is hidden
│
17 │ @type routes :: [Phoenix.Router.Route.t()]
│ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
│
└─ lib/routex/extension.ex:17: Routex.Extension (module)
Partial solution
In a related Github issue the users works around the module being hidden, by setting skip_undefined_reference_warnings_on. So I applied the same solution.
skip_undefined_reference_warnings_on: ["Routex.Extension","Routex.Processing", "Routex.Route"]
Now, the warnings are gone.
Remaining problem
With the workaround in place, I can add undefined references in 3 modules without being warned.
Question
Who has an idea how to solve this issue?
Solution #1: add a types.ex as a shim so you only need to exclude the shim module.
Solution #2: …?
Most Liked
LostKobrakai
You cannot just rely on defp/@typep for project level privacy. They only help with the module level. The convention of using @moduledoc false has been used for a long time in elixir itself and many 3rd party projects to define what is meant to be the public api or not.
LostKobrakai
How are you getting access to private structs? Why do you need to interact with them? Generally the solution would be to not depend on things you’re not expected to depend on.
LostKobrakai
@moduledoc false denotes the whole module as private to the library – hence the ex_doc warning.
BartOtten
Nope, this is pre-1.18 behavior. I ignored the warnings for a long time as I was aware they were only emitted by ExDocs. Dialyzer uses the type information without issues afaik. After all, types are mainly used for automated checks not as documentation for humans.
So to summarize:
- ExDocs warns because it does not want to link to an undocumented type / non-existing page. (works)
- Not linking can be done with
:skip_code_autolink_to(works) - Referencing in docs (@doc or .md) should cause a warning (works)
- Referencing an @type in @type should just work* (fails, causes warning in ExDoc)
Any objections to this summary / opinion? 
Popular in Questions
Other popular topics
Latest on Elixir Forum
Sponsor Spotlight
Build Elixir applications with speed and confidence.
Categories:
Sub Categories:
Forums
Our Sponsors
Build Elixir applications with speed and confidence.
Supporting innovation across the BEAM ecosystem.
We build reliable cloud platforms for business-critical systems.
Catch errors, track performance, monitor hosts and more.
Practical resources that improve the lives of professional developers.
Producing high quality Elixir screencasts since 2017.
The deployment platform built for Elixir: PaaS ease, VPS control.
Courses that'll move you from confusion to "Aha, now I get it!"