New EEP draft: module attributes for documentation

[Adam Lindberg]

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/766aa329/attachment-0001.htm>