[Numpy-discussion] Default value in documentation

Robert Kern robert.kern@gmail....
Tue Oct 2 12:40:28 CDT 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