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] > <javascript:>> 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] >> <javascript:>> 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? >> >> >> >
