[SciPy-user] Docstring standards for NumPy and SciPy
oliphant.travis at ieee.org
Wed Jan 17 16:57:55 CST 2007
Fernando Perez wrote:
> On 1/17/07, Gary Ruben <gruben at bigpond.net.au> wrote:
>>I think the :Returns: section is missing.
>>Is see-also to be included at the end of the Notes section. For
>>see-also, Ed says we can just add ":see: `frobble`" markup, so we should
>>be able to just add a line like in the numpy example list on the wiki.
>>I'm not clear on what the :Keywords: section adds. I think the 2nd
>>example is just as good.
> No, please let's explicitly differentiate between keywords and
> positional arguments. I don't care much what they are called, but
> there's a sharp functional difference in the language between the two:
> you can NOT omit positional arguments while you can omit keywords (or
> call them arguments-with-defaults, or whatever).
But, whether or not one has a positional or keyword argument is obvious
from the calling information, right?
I guess if you are using def f(*args, **kwds) then it isn't obvious.
In that case (which I would discourage generally), I would suggest
using separate :Parameters: and :Keywords: sections
I guess I'm leaning toward a single :Parameters: section with an empty
line distinguishing between "essential" and "little" used keyword
arguments (it is up to the author to decide what that means).
The other acceptable distinction would be to use separate :Parameters:
and :Keywords: sections.
Many people maybe unclear, but basically these sections are interpreted
by epydoc (they are not standard reST). This is why we can get rid of
the back-ticks and have epydoc process the documentation as if the
back-ticks were actually there.
More information about the SciPy-user