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
