New EEP draft: module attributes for documentation

[José Valim]

Adam, I have updated the EEP to mention the possibility of hiding docs:

    -doc "Foo".
    -doc hidden.


*José Valimhttps://dashbit.co/ <https://dashbit.co/>*


On Wed, Jun 2, 2021 at 7:08 PM Adam Lindberg <hello@REDACTED> wrote:

> I prefer that. I like when you can comment out or delete a line to reach
> the desired effect. :-)
>
> Another idea I had was that options could allow for a single option, e.g.
> -doc(hidden), or a map in case more options are added in the future, e.g.
> -doc(#{hidden => true}).
>
> Cheers,
> Adam
>
> On 2. Jun 2021, at 19:03, José Valim <jose.valim@REDACTED> wrote:
>
> 
> Hi Adam, thanks for the feedback.
>
> About point 1, what do you think about this:
>
> -doc "foobar".
> -doc hidden.
>
> For the cases you want to document but then hide it?
>
> *José Valimhttps://dashbit.co/ <https://dashbit.co/>*
>
>
> On Wed, Jun 2, 2021 at 7:00 PM Adam Lindberg <hello@REDACTED> wrote:
>
>> Hi,
>>
>> First of all, nice initiative!
>>
>> Two comments:
>>
>> (1) I think the hidden setting should be a different attribute or
>> argument rather than take the place of the actual documentation. I think
>> there’s value in allowing to fully documentation a module and all its
>> functions (including private ones).
>>
>> I would suggest two options: either (a) add a -docopts attribute that can
>> modify the following -moduledoc or -doc attribute, or (b) support an
>> additional argument to the doc attributes, e.g. -doc(hidden, “The
>> documentation.”).
>>
>> I think tools could show hidden documentation in a nice way if requested
>> by the user, for example. Or, you could easily hide a new API until it is
>> ready to be released, and then just remove the hidden flag.
>>
>> (2) I would not keep the existing syntax for EDoc and its generation to
>> HTML. I’d very much prefer a modern standardized format instead.
>>
>> Cheers,
>> Adam
>>
>> On 2. Jun 2021, at 13:34, José Valim <jose.valim@REDACTED> wrote:
>>
>> 
>> Abstract: This EEP draft proposes a structured documentation API for
>> Erlang where the documentation is handled as part of the language parser
>> and included directly in the compiled .beam files, as a replacement for
>> EDoc. Python, Elixir, and Clojure are examples of languages that follow
>> this approach of treating documentation as data rather than code comments.
>>
>> Pull request here: https://github.com/erlang/eep/pull/24
>>
>> Feedback is welcome.
>>
>> _______________________________________________
>> eeps mailing list
>> eeps@REDACTED
>> http://erlang.org/mailman/listinfo/eeps
>>
>>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://erlang.org/pipermail/eeps/attachments/20210603/aaef127e/attachment.htm>