Description
Is your feature request related to a problem? Please describe.
Using the new documentation system, I noticed a distinct difference in behaviour of the Erlang compiler compared to Elixir. The Elixir compiler, unless explicitly supressed with @moduledoc false
, always generates a "stub" doc chunks with the list of functions/macros/types/etc. In contrast, the Erlang compiler doesn't generate anything unless the module has at least one -moduledoc
or -doc
attributes.
This behaviour is problematic when trying to access the documentation or generate the documentation with ex_doc
. The list of exported functions and types, even if without explicit documentation is still a useful artefact. In the limit, where the project is starting to embrace the new documentation system, you end up with no documentation whatsoever - a list of modules and their public functions/types would be useful to have and better than nothing. This was also very frustrating - and meant I spent quite some time trying to understand if the toolchain was broken somewhere that we were ending up with empty documentation.
Describe the solution you'd like
If the current behaviour of the compiler is intentional to avoid "bloat" of .beam
files if the new feature is not used, we should at least expose a compiler option that would force the compiler to always generate chunks for modules, unless explicitly suppressed.
Describe alternatives you've considered
The alternative is to do a mass code-mod of the codebase adding some sort of "dummy" -moduledoc "".
attribute, but this feels rather silly and counterproductive.