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, jgabri...@gmail.com 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
