[Numpy-discussion] Docstring standards for NumPy and SciPy

[Christian Marquardt]

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.