[Numpy-discussion] Default value in documentation

[Robert Kern]

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