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] <javascript:>> > 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 >> >
