I hadn't looked at Docile in a long time, and from the commit history clearly there has been a lot of recent development.
Based on a very brief look, I'd say it's so much better than what we (don't) have that, as long as Michael says he's committed to continuing its development, I'd favor merging it to base in the next 30 seconds or so. Seriously. This has dragged on so long, let's go for it. Docile looks very good, and as we discover we need more features or changes in behavior, we can do it. --Tim On Thursday, September 11, 2014 03:17:45 PM Leah Hanson wrote: > If I understand correctly, Docile.jl is a macro-based implementation of > SGJ's suggestion, right? So if we're in agreement about non-comment-based > documentation, we could start using that now, and later switch from "@doc" > to the keyword "doc" when it's implemented. > > Are any packages documented with Docile? That would be a good illustration > of how well this works. > > -- Leah > > On Thu, Sep 11, 2014 at 3:10 PM, Jason <[email protected]> wrote: > > Why is begin...end better than """....""" ? > > > > > > For block documentation they are equivalent, but the triple quotes are > > heavy for lots of single line comments. Eg: look at the average comment > > length of this randomly chosen Haskell source file > > <http://hackage.haskell.org/package/vector-0.6.0.2/docs/src/Data-Vector.ht > > ml> . > > > > But in the end, it's just bikeshedding over style at this point. It looks > > > > like most of us are in agreement about: > > 1. Coupling the documentation to the AST > > 2. Documentation being markup agnostic/flexible > > > > Now it's just a matter of syntax. Which ironically can sometimes derail > > entire language features for years at a time. Eg: better record syntax > > <https://ghc.haskell.org/trac/ghc/wiki/Records> in Haskell has been in > > the need of the right syntax (although semantics are a hangup there as > > well) for many years. > > > > Perhaps we need a temporary BDFL > > <http://www.wikiwand.com/en/Benevolent_dictator_for_life> for Julia to > > just make an arbitrary (good) decision and get us all into the glorious > > days of documented packages.
