[Numpy-discussion] Default value in documentation

[Charles R Harris]

On 10/2/07, Robert Kern <robert.kern at gmail.com> wrote:
>
> 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.


I've been putting the default value first among the options. Thus

    axis : {-1, integer}, optional

Chuck
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/numpy-discussion/attachments/20071002/9e920743/attachment.html>