Very nice! > """ > one-line summary not using variable names or the function name
I would personally prefer that the first name contains the function (but nor arguments) - that way, when you are scrolling back in your terminal, or have a version printed out, you know what function/method the doc string belongs to without having to refer to examples lower down. > A few sentences giving an extended description. After the general description, but before giving the inputs and outputs, wouldn't it make sense to give the function signature as well? Something like named, list, of, outputs = my_function(var1, variable2 [,kwdarg1=...]) This would again reduce the need to have an extra look into the example section. Using the brackets, optional arguments and default settings could also be communicated easily. > Inputs: > var1 -- Explanation > variable2 -- Explanation [...skipped a bit...] > Notes: > Additional notes if needed > Authors: > name (date): notes about what was done > name (date): major documentation updates can be included here also. I'm all for mentioning the authors (certainly in the main docstrings of a module, say). *But* I would put that information at the very end of a docstring - when reading documentation, I'm primarily interested in the usage information, examples, the 'See also' and further notes or comments. Having to skip author names and even a (possibly long) list of modifications somewhere in the middle of the docstring, i.e. before getting to the that information I'm looking for each time seems like an annoyance (to me) that is not really necessary. Hope this helps / is useful, Christian. _______________________________________________ Numpy-discussion mailing list Numpy-discussion@scipy.org http://projects.scipy.org/mailman/listinfo/numpy-discussion
