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.html> > . > > 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. >
