Looks good. I’d allow the same for -moduledoc as well. Cheers, Adam
> On 3. Jun 2021, at 11:55, José Valim <[email protected]> wrote: > > > Adam, I have updated the EEP to mention the possibility of hiding docs: > > -doc "Foo". > -doc hidden. > > > José Valim > https://dashbit.co/ > > >> On Wed, Jun 2, 2021 at 7:08 PM Adam Lindberg <[email protected]> wrote: >> I prefer that. I like when you can comment out or delete a line to reach the >> desired effect. :-) >> >> 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}). >> >> Cheers, >> Adam >> >>>> On 2. Jun 2021, at 19:03, José Valim <[email protected]> wrote: >>>> >>> >>> 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é Valim >>> 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
