Skip to content

Add option to force compiler to always generate doc chunks #9404

Open
@michalmuskala

Description

@michalmuskala

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementhelp wantedIssue not worked on by OTP; help wanted from the communityteam:VMAssigned to OTP team VM

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions