Hi John,
Another might be to support having docstrings in separate files (e.g., foo.jl and an optional corresponding foo.jldoc for detailed docstrings). Docile.jl does support this feature already with: @doc meta(file = "foobar-docs.md") -> foobar(x) = x Granted the syntax is slightly bulky, but it does allow arbitrary metadata to be associated with any Julia objects via keyword arguments. This *isn’t* available in the doc system in Base since it was best to start off with a smaller feature set and extend it later. Anecdotally, I’ve found that storing long docs in external files to be much more pleasant than wading through them in source files. — Mike On Wednesday, 17 December 2014 10:38:04 UTC+2, [email protected] wrote: > > 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 > >
