[Numpy-discussion] Default value in documentation
Robert Kern
robert.kern at gmail.com
Tue Oct 2 13:40:28 EDT 2007
Pierre GM wrote:
> All,
> I'm starting to update the documentation of maskedarray to the latest
> standard.
> How should I represent the default value of an optional parameter ?
> I was thinking something like
>
> def function(a, value=None)
> """Does something
> *Parameters*:
> a : {ndarray}
> Input array.
> value : {float} *[None]*
> Some value. If None, a default based on the dtype of a is used.
> """"
I prefer this:
value : {float}, optional
Some value. If not provided, a default based on the dtype of a is used.
So label it optional and describe the default in prose in the parameter
description if necessary. While this is less descriptive for meaningful defaults
(axis=-1), the case you show above is precisely suited to it. None is not really
the default value, it's really just being used as a marker for "argument not
provided". And for the meaningful defaults, the function signature is more than
adequate to provide the necessary information.
--
Robert Kern
"I have come to believe that the whole world is an enigma, a harmless enigma
that is made terrible by our own mad attempt to interpret it as though it had
an underlying truth."
-- Umberto Eco
More information about the NumPy-Discussion
mailing list