[SciPy-Dev] How to document parameters *args and **kwds
Fri Jun 11 10:45:03 CDT 2010
On Thu, Jun 10, 2010 at 7:36 PM, Robert Kern <firstname.lastname@example.org> wrote:
> On Thu, Jun 10, 2010 at 22:05, David Goldsmith <email@example.com>
> > On Thu, Jun 10, 2010 at 6:50 PM, Robert Kern <firstname.lastname@example.org>
> >> On Thu, Jun 10, 2010 at 21:45, David Goldsmith <email@example.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
> > 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
> > it un-escaped gets misinterpreted, too (as an un-closed emphasis
> > 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
> > will protest. :-) Regardless, right now, using * & ** "breaks" the Wiki,
> > whereas \* & \*\* keeps the Wiki from complaining, but the \ aren't
> > by it, and look ugly be it in a terminal or rendered. What to do, what
> > 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 excerpted this over on the Q+A page; please go check to confirm that I
haven't misrepresented you. And thanks for your input!
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the SciPy-Dev