[SciPy-user] Docstring standards for NumPy and SciPy

Travis Oliphant 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

So,

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.

-Travis




More information about the SciPy-user mailing list