Clarify the difference between empty map, none, and hidden in EEP 48

[josevalim]

This aligns the EEP with the usage of those values in Erlang/OTP XML, EDoc, and Elixir.

[josevalim]

@garazdawi I am totally fine with treating :none the same as %{}. The goal of this PR was exactly to align with your linked comment (and we changed ExDoc to align with your linked comment but we can revert it). /cc @erszcz

[erszcz]

As I understand it, the problem case was when:

• we used ExDoc to generate HTML from EDoc chunks
• a module in question had no ModuleDoc (none), but did have docs for functions

Ultimately, this lead to the module as a whole not getting an HTML page generated. https://github.com/erlang/otp/pull/5205 changes EDoc to return #{} as the default if no ModuleDoc is present, so that the ExDoc HTML still gets generated and functions docs are accessible there.

In comparison to shell_docs, as far as I understand:

• shell_docs prints There is no documentation for ?MODULE/?ENTRY if ModuleDoc is none
• but it prints docs for the functions of the module in question when invoked with h(M, F) - by defaulting ModuleDoc to none in EDoc we would not get the ExDoc HTML page generated at all, effectively hiding function documentation that might've been present

[josevalim]

@erszcz correct. The point though is that we made it so ExDoc treats none and %{} as distinct things, but we could make it so they are the same, so there is no need to merge the OTP PR.

[erszcz]

Indeed, one of the values seems redundant.

[garazdawi]

So to recap, that would mean that both none and #{} mean that the module/entry are public but contain no documentation. So it should show up in listings and show potential signature+metadata.

While ModuleDoc = hidden means that it is not public, and entry missor or Doc = hidden means that it is not public.

Erlang treats doc chunk missing as if ModuleDoc = none and all the exported functions have Doc = none. I suppose that this is not a problem that you have in Elixir, except for Erlang code that is.

[erszcz]

@garazdawi

entry missing or Doc = hidden means that it is not public.

I think the shell_docs logic you described above is spot on:

• entry missing -> There is no documentation for ?MODULE/?ENTRY
• Doc = hidden -> The documentation for <entry> is hidden. This probably means that it is internal and not to be used by other applications. (in case of EDoc it's a hint you might actually get the docs visible by providing the private option to EDoc)

[josevalim]

We are all on the same page. I will close this PR and update ExDoc. We can probably close the OTP PR for Edoc too. Thanks!

[garazdawi]

@garazdawi

entry missing or Doc = hidden means that it is not public.

I think the shell_docs logic you described above is spot on:

• entry missing -> There is no documentation for ?MODULE/?ENTRY
• Doc = hidden -> The documentation for <entry> is hidden. This probably means that it is internal and not to be used by other applications. (in case of EDoc it's a hint you might actually get the docs visible by providing the private option to EDoc)

This not how shell_docs behaves today. For entry missing it prints nothing, only returns {error,function_missing}. Example:

1> h(user, start).
{error,function_missing}

This is the same return you get if you put a function that actually does not exist:

1> h(user, start_me_up).
{error,function_missing}

I wonder if we should start generating hidden entries for functions that are exported but not documented in erl_docgen... just as we generate ModuleDoc hidden for modules that are not public.

[josevalim]

Oops, misclick. Sorry.