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 <[email protected]> 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 <[email protected]> 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 > [email protected] > http://erlang.org/mailman/listinfo/eeps > >
_______________________________________________ eeps mailing list [email protected] http://erlang.org/mailman/listinfo/eeps
