I'll just reply to everything here [1] since this thread is getting rather big.
[1] https://gist.github.com/MichaelHatherly/7fb3ee1461eac9e02020 On Thursday, 12 June 2014 14:20:25 UTC+2, Mauro wrote: > > @Ivar: thanks for the clarification on helpdb.jl. > > > Using a `_str` macro as in doc"" to mark documentation has been > suggested > > before, and I think it is a terrific idea to use that syntax to enable > an > > extensible advanced formatting (like Markdown, LaTeX, HTML?, Textile, > > Doxygen) that can be converted to any form of pretty display (inline IDE > > doc, HTML, pdf etc..). That way anyone can extend the system to support > his > > favorite documentation format, by creating a new @myformat_str macro > that > > returns an object that can be rendered into text + HTML and the other > > formats he might use. > > Yep, this custom formatting has been suggested (e.g. by Steven in > https://github.com/JuliaLang/julia/issues/3988). But here I more > thought of having the `doc` as a visual label as opposed to having > unadorned strings floating around the code. > > Now, more bike shedding! Here a gist with some thoughts on documenting > methods vs generic functions: > https://gist.github.com/mauro3/8345b47c1ed467054283 > > This would associate doc-strings with the individual methods. > Additionally, a doc string could also be added to the generic function. >
