> 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
