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

[Robert Kern]

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
me.

*args
    Arguments to pass to the callback.
**kwds
    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