
<html><head><meta http-equiv="content-type" content="text/html; charset=utf-8"></head><body dir="auto">Hi,<div><br></div><div>First of all, nice initiative!</div><div><br></div><div>Two comments:</div><div><br></div><div>(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). </div><div><br></div><div>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.”).</div><div><br></div><div>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.</div><div><br></div><div>(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. <br><br><div dir="ltr">Cheers,<div>Adam</div></div><div dir="ltr"><br><blockquote type="cite">On 2. Jun 2021, at 13:34, José Valim <jose.valim@gmail.com> wrote:<br><br></blockquote></div><blockquote type="cite"><div dir="ltr"><div dir="ltr"><div></div><div>Abstract: <span class="gmail-blob-code-inner gmail-blob-code-marker">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.</span></div><div><span class="gmail-blob-code-inner gmail-blob-code-marker"><br></span></div><div><span class="gmail-blob-code-inner gmail-blob-code-marker">Pull request here: <a href="https://github.com/erlang/eep/pull/24">https://github.com/erlang/eep/pull/24</a></span></div><div><br></div><div>Feedback is welcome.</div><br></div>

<span>_______________________________________________</span><br><span>eeps mailing list</span><br><span>eeps@erlang.org</span><br><span>http://erlang.org/mailman/listinfo/eeps</span><br></div></blockquote></div></body></html>