In general, there should be a single doc string for a generic function. It explains the concept and meaning of the function with variations on usage. The major difference between Python/Matlab and Julia in terms of doc strings is that there isn't a single place where the function is defined; there isn't always a single "most generic" method of a function. That's why having the docstring inside one particular method seems wrong to me. Having it precede a series of method definitions of the same generic function – and grouping them is typical – makes the most sense. Unlike Matlab and Python, when you're moving a function, you'll typically move all of it's methods anyway, so the cut-and-paste argument seems pretty moot.
> On Jun 12, 2014, at 9:03 AM, Mauro <mauro...@runbox.com> wrote: > >> On Thu, 2014-06-12 at 13:43, mike.j.in...@gmail.com wrote: >> Is there a particular reason to document functions as opposed to just >> methods? I would have thought that documentation for the most generic >> method + some specific methods where necessary would be enough. It's best >> if documentation is as simple as possible – we do want to encourage people >> to use it. > > The generic function doc should be generic, whereas methods doc can be > more specific. Probably, the default should be that if only one method > is documented this is taken as the one documentation. For instance, if > you look at `help(length)`, it starts getting a bit confusing. > Shouldn't there be an generic introduction and then the specific > methods? > > An example could be `base/graphics.jl` which defines lots of interface > functions. It would be good if `base/graphics.jl` could define the > generic function documentation and a package implementing `graphics.jl` > could add specific methods documentation. > >> Custom formatting might be a useful feature, but I think it's best if >> plain docs are treated as Markdown by default – having consistency in >> the way code blocks etc. are formatted will be helpful even when >> viewing documentation as plain text, especially now that we can view >> Markdown in the terminal. > +1
