We don't need flexible documentation – we need one simple documentation system that works.
On Thu, Aug 28, 2014 at 4:50 PM, Leah Hanson <[email protected]> wrote: > 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? >>>>> >>>>> >>>>> >>>> >>> >> >
