
<html><head><meta http-equiv="content-type" content="text/html; charset=utf-8"></head><body dir="auto">I prefer that. I like when you can comment out or delete a line to reach the desired effect. :-)<div><br></div><div>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}).<br><div><br><div dir="ltr">Cheers,<div>Adam</div></div><div dir="ltr"><br><blockquote type="cite">On 2. Jun 2021, at 19:03, José Valim <jose.valim@gmail.com> wrote:<br><br></blockquote></div><blockquote type="cite"><div dir="ltr"><div dir="ltr"><div>Hi Adam, thanks for the feedback.</div><div><br></div><div>About point 1, what do you think about this:</div><div><br></div><div style="margin-left:40px">-doc "foobar".</div><div style="margin-left:40px">-doc hidden.<br></div><div><div><div dir="ltr" class="gmail_signature" data-smartmail="gmail_signature"><div dir="ltr"><div><div dir="ltr"><div><div><br></div><div>For the cases you want to document but then hide it?<br></div><div><br></div><span style="font-family:arial,sans-serif;font-size:13px;border-collapse:collapse"><b><span style="border-collapse:separate;font-family:arial;font-weight:normal"><div><span><div><span style="font-size:13px"><div><span style="font-family:arial,sans-serif;font-size:13px;border-collapse:collapse"><b>José Valim</b></span></div><div><span style="font-family:arial,sans-serif;font-size:13px;border-collapse:collapse"><div><span style="font-family:verdana,sans-serif;font-size:x-small"><a href="https://dashbit.co/" style="color:rgb(42,93,176)" target="_blank">https://dashbit.co/</a></span></div></span></div></span></div></span></div></span></b></span></div></div></div></div></div></div><br></div></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Wed, Jun 2, 2021 at 7:00 PM Adam Lindberg <<a href="mailto:hello@alind.io">hello@alind.io</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div 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 <<a href="mailto:jose.valim@gmail.com" target="_blank">jose.valim@gmail.com</a>> wrote:<br><br></blockquote></div><blockquote type="cite"><div dir="ltr"><div dir="ltr"><div></div><div>Abstract: <span>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><br></span></div><div><span>Pull request here: <a href="https://github.com/erlang/eep/pull/24" target="_blank">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><a href="mailto:eeps@erlang.org" target="_blank">eeps@erlang.org</a></span><br><span><a href="http://erlang.org/mailman/listinfo/eeps" target="_blank">http://erlang.org/mailman/listinfo/eeps</a></span><br></div></blockquote></div></div></blockquote></div>

</div></blockquote></div></div></body></html>