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