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? >> >> >
