numpy/numpy — pull request #4641 by gdementen (2014-04-25 11:36:45+00:00)
Title: DOC: standardize "size" arg description in random module docstrings

There were many different versions for no good reason.

I tried to combine the useful bits in all common docstrings and came up with this:

size : int or tuple of ints, optional
Output shape. If the given shape is, e.g., ``(m, n, k)``, then
``m * n * k`` samples are drawn. Default is None, in which case a
single value is returned.

However, at the end, I found the docstring for zipf, which adds the following precision:

... a single integer is equivalent in
its result to providing a mono-tuple, i.e., a 1-D array of length
*size* is returned.

So, I should probably include that sentence in all docstrings too. Thoughts?

PS: the module would really benefit from more docstring standardisation:
* descriptions for (other) arguments of many functions do not include the default value
* "optional" in arg description is missing in a lot of places
* returns should also be standardized
* possibly raises too

I will probably do this one day, but it might take a while...