New EEP draft: module attributes for documentation

[Adam Lindberg]

Looks good. I’d allow the same for -moduledoc as well.

Cheers,
Adam

> On 3. Jun 2021, at 11:55, José Valim <jose.valim@REDACTED> wrote:
> 
> 
> Adam, I have updated the EEP to mention the possibility of hiding docs:
> 
>     -doc "Foo".
>     -doc hidden.
> 
> 
> José Valim
> 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é Valim
>>> 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/d2714b7f/attachment.htm>