[SciPy-Dev] How to document parameters *args and **kwds

[David Goldsmith]

On Thu, Jun 10, 2010 at 6:50 PM, Robert Kern <robert.kern at gmail.com> wrote:

> On Thu, Jun 10, 2010 at 21:45, David Goldsmith <d.l.goldsmith at gmail.com>
> wrote:
> > We've kind of discussed *args before (see
> > http://docs.scipy.org/numpy/Questions+Answers/#variable-arguments),
> though
> > we didn't note a "canonical answer."  Can we:
> >
> > A) agree on such, and
> >
> > B) extend it to parameter **kwds?
>
> In most cases, I would leave the type field blank unless if they
> happen to be homogeneous. They often aren't.
>
> *args :
>    Arguments to pass to the callback.
> **kwds :
>    Keyword arguments to pass to the callback.
>
> But sometimes they are.
>
> *indices : ints
>    Possibly multiple indices.
>
> I don't think Sphinx has a problem with these constructs, but I could be
> wrong.
>

What we were (only slightly) leaning to in the Q+A page discussion, in part
because Ralf said there was already precedent for it in the docs, was:

\*args : Arguments

Explanation of number and type of arguments ....

but escaping the '*' with an '\' doesn't appear to be working, but leaving
it un-escaped gets misinterpreted, too (as an un-closed emphasis mark-up).
So the **kwds analog would be

\*\*kwds : Keyword arguments
    Explanation of number and type...

but now that I look at that typed out, I predict that the command-line crowd
will protest. :-)  Regardless, right now, using * & ** "breaks" the Wiki,
whereas \* & \*\* keeps the Wiki from complaining, but the \ aren't removed
by it, and look ugly be it in a terminal or rendered.  What to do, what to
do...

DG
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/scipy-dev/attachments/20100610/d1a7623c/attachment.html>