On Wednesday, December 17, 2014 6:47:03 AM UTC-5, Michael Hatherly wrote: > > 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. > Perhaps the convention could be: each foo.jl source file may have a corresponding foo.md file (alongside it, in the source directory), and each thing documented with @doc may have its own H1 in the .md file.
This way, rather than having to explicitly/verbosely say `@doc meta(file = "foo.md#foobar" -> foobar(x) = x` (that is, come up with id's and add them explicitly to the .md file), the tools would know right where to look for external docstrings. -- John
