[Doc-SIG] Comments on the PEP 257 example

[Tony J Ibbs (Tibs)]

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.)