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

Robert Kern robert.kern@gmail....
Thu Jun 10 21:36:58 CDT 2010

On Thu, Jun 10, 2010 at 22:05, David Goldsmith <d.l.goldsmith@gmail.com> wrote:
> On Thu, Jun 10, 2010 at 6:50 PM, Robert Kern <robert.kern@gmail.com> wrote:
>> On Thu, Jun 10, 2010 at 21:45, David Goldsmith <d.l.goldsmith@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

    Arguments to pass to the callback.
    Keyword arguments to pass to the callback.

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 SciPy-Dev mailing list