On Mar 7, 2012 7:11 AM, "Philip Martin" <philip.martin_at_wandisco.com> wrote:
>
> 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?
Geez. Be smart, Philip. Obviously, that quoted content is dumb. I'm talking
about format. Specifically not following the basic rule of "one line
summary. One blank line. Details." Julian's change is missing the blank
lines, which many tools parse.
Doxygen has formats. Python has PEP-257.
-g
Received on 2012-03-07 13:36:25 CET