Yes, that's it. I've partially written a custom generator for it in the past; plugging into the API was pretty easy, the hard part was understanding some of the internal type-representation data structures that it exposed. The API exposes the AST to the plugin, which allows the plugin to be more powerful than just a list of comments. Like Go, OCaml uses a separate tool for building documentation; however, this is not the cool part that I wanted to point out. The interesting idea to me was that it exposes the AST and metadata to any interested OCaml plugin, and that it was pretty straight-forward to get a basic plugin working.
It's important to me that there's an API for accessing the metadata & associated AST in a way that allows for more creative displays (i.e. Haskell's fancy type-aware search engine Hoogle <http://www.haskell.org/hoogle/> (built using Haddock) or some other visualization or fancy IDE integration). This would also be an API that a package for building documentation websites/manuals could use. I like Steven Johnson's proposal, and I think it already allows/has this -- since you can look up the metadata for a Function/Method/Module/etc, and you can already get those within Julia (all functions/etc in a Module, etc), this should "just work". (I was initially expecting a comment-base approach, which I've seen work well in languages where I've used it (OCaml, Java) with a notation (@author, etc) for metadata embedded in comments. However, I think Julia has much cooler things it can do with special string parsers (md"") and writemime, and the flexibility of documentation format should really benefit from that. A potential oddness is that we might end up with "dependencies only for documentation" the way we have dependencies only for testing, since you might have a package that defines your special documentation string, but isn't otherwise used in your code.) On Wed, Aug 27, 2014 at 5: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? >>>> >>>> >>>> >>> >> >
