[Doc-SIG] Comments on the PEP 257 example
Tony J Ibbs (Tibs)
tony@lsl.co.uk
Fri, 3 Aug 2001 11:01:53 +0100
Looking at Guido's example docstring
====================================
Guido's example as presented::
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 not valid reST_. Whilst that's not entirely unreasonable (since
the DPS is not tied to reST), it would, I think, be consistent if
it were recast as such.
Trying to do this might, for instance, give us::
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
...
Mind you, at this point I think one can see that Guido won't want to
*use* a descriptive list for this, as we know he dislikes that
appearance (indeed, the original example is much easier to read).
It also becomes clear why I wanted "paragraph labels" to work as I
had them, so that one can *identify* that one has arguments to be
worked on. A title won't do, because one doesn't want a title for
the text that might *follow* the arguments...
There's more I want to write on this - an updated version will follow at
some time...
--
Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/
"How fleeting are all human passions compared with the massive
continuity of ducks." - Dorothy L. Sayers, "Gaudy Night"
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)