[SciPy-user] Docstring standards for NumPy and SciPy
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.
>> name (date): notes about what was done
>> name (date): major documentation updates can be included here
> 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.
"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