[SciPy-user] Docstring standards for NumPy and SciPy

Robert Kern robert.kern at gmail.com
Wed Jan 10 13:29:01 CST 2007


Stefan van der Walt wrote:
> On Wed, Jan 10, 2007 at 07:43:28AM -0700, Travis Oliphant wrote:
>> Outputs:  named, list, of, outputs
>>    named   -- explanation
>>    list    -- more detail
>>    of      -- blah, blah.
>>    outputs -- even more blah
> 
> Why list the outputs when they follow in the list?

On first glance, it's difficult for a new user to understand that the list is
describing elements of a tuple. I can go either way on this, though. I use a
substantially similar format at work, and I don't include the redundant list.

>> Authors:
>>    name (date):  notes about what was done
>>    name (date):  major documentation updates can be included here
>>    also.
> 
> I don't much like the idea of author info in the docstring.  We have
> an SVN log and a credits file.  This doesn't enhance the reader's
> understanding of the function usage.

Agreed.

-- 
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-user mailing list