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] > <javascript:_e(%7B%7D,'cvml','[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? >>> >>> >>> >> >
