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 >
