New EEP draft: module attributes for documentation

[José Valim]

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/20210602/d54a3b1f/attachment.htm>