On Tuesday, December 16, 2014 4:55:39 PM UTC-5, Ivar Nesje wrote: > > * 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, Ivar.
Regarding concerns of longish docstrings being cumbersome to edit around, one solution might be to use your editor's code-folding to by-default hide docstrings. Another might be to support having docstrings in separate files (e.g., foo.jl and an optional corresponding foo.jldoc for detailed docstrings). -- John
