Listing multiple `-doc` attributes for the same function

[robertoaloi]

Describe the bug
In the EEP 59 proposal, it is stated that:

Listing multiple -doc attributes with string values for the same function should warn or error accordingly, unless the documentation is being set to hidden. For example, this is valid:

-doc "Example".
-doc hidden.
example() -> ok.

This does not seem to be the case though.

To Reproduce
Have the module:

-module(test).

-export([example/0]).

-doc "Example".
-doc hidden.
example() ->
  ok.

Compile it with:

$ erlc test.erl
test.erl:8:2: redefining documentation attribute (doc) previously set at line 5
%    8| -doc hidden.
%     |  ^

Expected behavior
No error is produced.

Affected versions
OTP 27.3

[garazdawi]

This was a delibarate decision to diverge from the EEP that we made while implementing it. Apparently I did not get around to updating the EEP.

Our reasoning was that when the docs are read from eep-48 chunks the data is not available anyway, so there is nothing to be gained by doing like this instead of just writing the documentation as a comment.

How do you make use of this information in ELP?

[robertoaloi]

I just noticed this while converting old-style edoc comments to Markdown via ELP. Since I was following the EEP59 specification, I was converting @private tags to the corresponding -doc hidden. In a few cases, a function had both edoc comments and the @private tag, which resulted in a compilation error.

It's not a big deal. The main usage could be for IDEs to show the Edoc (now markdown) comments on hover/auto-completion while preserving the -doc hidden attribute which would not publish the docs e.g. via ex_doc.

[garazdawi]

Then I propose that we update the EEP to reflect the implementation until such a time that some tool can make use of this information at which point we can revisit it.

[garazdawi]

Fix in erlang/eep#78