It's not really that worthwhile since (a) you can use Docile and (b) the future syntax
""" foo """ foo() ... is backwards-compatible already. I just use that. On 16 December 2014 at 22:37, <[email protected]> wrote: > > Since the @doc is 0.4, is it possible to backport a "do nothing" version > that will allow documented code to still compile in 0.3? > > Cheers > Lex > > On Wednesday, December 17, 2014 8:04:06 AM UTC+10, Mike Innes wrote: >> >> Actually the @doc macro will still interpret plain strings as markdown by >> default. There are some caveats with escaping that make it good practice to >> write doc"" anyway, but those will go away once the parser changes are >> implemented. >> >> I'm in the process of writing documentation documentation, so the manual >> should be up to date reasonably soon. >> >> On 16 December 2014 at 21:55, Ivar Nesje <[email protected]> wrote: >>> >>> > Hi, >>> >>> Hello. >>> >>> > Looks like exciting doc changes are afoot with Julia! I'd like to get >>> some more understanding of what's coming. Had a look at some of the github >>> issues tagged "doc", but I'm still missing some basics (note, I'm still >>> quite new to Julia). Questions: >>> >>> * Is code from Docile.jl, Lexicon.jl, and Markdown.jl being used / >>> incorporated into Julia proper? >>> >>> Yes. >>> >>> * Will the new syntax be `doc "..."`, `@doc "..." ->`, or something >>> else? >>> >>> The -> is probably going away, but final syntax is not yet set in stone >>> (nor in code). >>> >>> * What is `md"Some *text* here`? Will Julia support and/or require >>> that for the new docstrings? If so, what is the benefit of `md"this"` over >>> `"this"`? >>> >>> The benefit is that `md"this"` has an explicit format, so that we can >>> have more formats in the future. The value has been discussed and you can >>> have different formats by other means. I like the way it makes markdown >>> optional, but others want to save two characters to type. >>> >>> * Regarding the docs currently at <http://docs.julialang.org/en/ >>> release-0.3/>, does all of that content currently come only from the >>> contents of julia/doc and below? >>> >>> Yes >>> >>> * Will the docstrings in 0.4 be online at, say, >>> http://docs.julialang.org/en/release-0.4/ , integrated with the >>> rendered .rst docs? Or are they intended to be strictly available via the >>> repl? Hm... to avoid duplication, are any files in julia/doc slated to be >>> diced up, reformatted into markdown, and inserted into source as docstrings? >>> >>> Maybe, but it's hard to predict the future. Many files in Base are too >>> long already, and detailed docs will not make them shorter. For huge >>> codebases, I think it makes sense to fit as much code as possible on a >>> screen, and search in separate docs if I need to know more about a function. >>> >>> Thanks, >>> -- John >>> >>
