Do you need one file per docstring, or can you pack the docs for many functions in one file?
One file per docstring currently. My thinking was that docstrings that are short enough to warrant packing several into a single file are probably short enough that they could go directly into the source code. Also, how would different “subdocstrings” be associated with different methods? Syntax such as: @doc meta(file = "docs.md#foobar") -> foobar(x) = x with a corresponding # foobar in docs.md to link the two together might work. I’ll probably add this at some point soon. Some relevant links: - https://github.com/MichaelHatherly/Docile.jl/issues/48 - https://github.com/MichaelHatherly/Lexicon.jl/issues/18 — Mike On Wednesday, 17 December 2014 13:18:57 UTC+2, Tim Holy wrote: > > Do you need one file per docstring, or can you pack the docs for many > functions > in one file? I think you'd need to be able to do the latter if we want > there to > be some kind of automatic correspondence between foo.jl and foo.jldoc. > > --Tim > > On Wednesday, December 17, 2014 01:23:45 AM Michael Hatherly wrote: > > 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 > >
