Haskell also has a similar approach with Haddock <http://www.haskell.org/haddock/#Overview>, which allows the generation of documentation for the entire package ecosystem at one location: http://hackage.haskell.org/
Here's an example page: http://hackage.haskell.org/package/vector-0.10.11.0/docs/Data-Vector-Generic.html On Wed, Aug 27, 2014 at 4:09 PM, John Myles White <[email protected]> wrote: > Is it this system, Leah? > http://caml.inria.fr/pub/docs/manual-ocaml-400/manual029.html > > -- John > > > On Aug 27, 2014, at 3:06 PM, Leah Hanson <[email protected]> wrote: > > I like OCaml's approach, which uses comments above functions/etc, and has > a neat plugin system to output them in various formats. > > On Wednesday, August 27, 2014, John Myles White <[email protected]> > wrote: > >> Ok, thanks for clarifying. I also like the idea of strategically placed >> comments as automatic documentation. >> >> -- John >> >> On Aug 27, 2014, at 2:54 PM, Job van der Zwan <[email protected]> >> wrote: >> >> Right, that's what I meant with GoDoc being a separate tool: Go is >> statically compiled and does not have something like a REPL or runtime >> evaluation, so being a separate tool is only logical. In that sense it's >> not a comparable situation. >> >> The comments-as-documentation and the conventions used to make it work >> might still be worth looking into. >> >> I personally feel that from the point of view of people using Julia it's >> a better option than introducing docstrings - comments are already the >> source-level form of documentation-for-humans after all. Introducing >> docstrings feels like creating two different options for the same role, >> except one is ignored by tools and the other isn't. That just *feels* >> unelegant to me (not the strongest argument, I know), and I worry that code >> with both would become visually more noisy. >> >> I just googled for possible reasons for having both docstrings and >> comments, and the only argument I found is that one describes the *what* >> and the other a *how*. GoDoc only counts comments above the >> package/variable/function definition as documentation, and ignoring >> comments inside a function body or struct definition. Since the former >> typically documents the *what* and the latter the *how* anyway, that >> distinction automatically emerges through convention. >> >> Of course, if "not discarding comments during compilation" would require >> a major overhaul to the compiler and docstrings are technically much easier >> to introduce I can understand if that option is more appealing - a less >> elegant feasible solution is better than an inelegant infeasable one. And >> perhaps there are other arguments in favour of having both docstrings and >> comments that I'm not aware of? >> >> On Tuesday, 26 August 2014 17:34:24 UTC+2, Stefan Karpinski wrote: >>> >>> To clarify – I meant that I like the style of GoDoc, not the fact that >>> you run the tool as a separate pass. That doesn't strike me as completely >>> out of the question, but wouldn't be optimal. >>> >>> >>> On Tue, Aug 26, 2014 at 11:32 AM, John Myles White <[email protected] >>> > wrote: >>> >>>> No, I was talking about what I understood to be a design principle of >>>> GoDoc: doc generation and parsing occurs at doc-gen time, not at run-time. >>>> >>>> Yes, you would have to make comments non-ignorable to get this to work. >>>> >>>> — John >>>> >>>> On Aug 26, 2014, at 12:44 AM, Job van der Zwan <[email protected]> >>>> wrote: >>>> >>>> On Tuesday, 26 August 2014 00:04:41 UTC+2, John Myles White wrote: >>>>> >>>>> The issue is that you want to have all code documentation show up in >>>>> REPL. In the GoDoc approach, this might require an explicit "build" step >>>>> -- >>>>> which is a non-trivial cost in usability. >>>>> >>>>> -- John >>>>> >>>> >>>> I assume you talking about GoDoc as a tool? >>>> >>>> In case you are referring to comments as the source of documentation >>>> instead of docstrings: I assume comments are now simply discarded during >>>> compilation, making it impossible to use them for documentation, but if >>>> that could be changed they should be just as valid as the format for >>>> documentation, right? >>>> >>>> >>>> >>> >> >
