Re: svn commit: r1297921 - /subversion/trunk/subversion/tests/cmdline/svntest/sandbox.py

Greg Stein <gstein_at_gmail.com> writes:

> On Wed, Mar 7, 2012 at 05:27, <julianfoad_at_apache.org> wrote:
>> Author: julianfoad
>> Date: Wed Mar  7 10:27:15 2012
>> New Revision: 1297921
>>
>> URL: http://svn.apache.org/viewvc?rev=1297921&view=rev
>> Log:
>> Improve doc strings of Sandbox.simple_*() test suite functions.
>
> If you're going to switch from single-line docstrings to multi-line,
> then please follow PEP-8 guidelines for docstrings, which actually
> just defers to PEP-257 on this matter:
> http://www.python.org/dev/peps/pep-0257/

This example docstring:

def complex(real=0.0, imag=0.0):
    """Form a complex number.

    Keyword arguments:
    real -- the real part (default 0.0)
    imag -- the imaginary part (default 0.0)

    """
    if imag == 0.0 and real == 0.0: return complex_zero
    ...

is just silly unless we are planning to make the docstrings available
without the source code. Duplication like that is pointless when
reading the code. What do we gain by writing docstrings in that form?

-- 
uberSVN: Apache Subversion Made Easy
http://www.uberSVN.com