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

[David Goldsmith]

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

> On Thu, Jun 10, 2010 at 22:05, David Goldsmith <d.l.goldsmith at gmail.com>
> wrote:
> > 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...
>
> Fix the wiki software. The generated Sphinx docs are fine with the
> unescaped version. The wiki is a tool to help build the Sphinx docs,
> not the other way around.
>
> However, my typeless examples do not work directly. You need to omit
> the colon. Shame, because I like the look of the colon. Ah well. The
> following do work, and I prefer them to the "Arguments" and "Keyword
> arguments" placeholders. The *, ** and usually the names of those
> variables usually state clearly that they are arguments or keyword
> arguments. Stating it a third time just seems weird. I'd say, add real
> type information if it makes sense, otherwise omit it. But that's just
> me.
>
> *args
>    Arguments to pass to the callback.
> **kwds
>    Keyword arguments to pass to the callback.
>
> --
> Robert Kern
>

I excerpted this over on the Q+A page; please go check to confirm that I
haven't misrepresented you.  And thanks for your input!

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