[Doc-SIG] Comments on the PEP 257 example

[David Goodger]

on 2001-08-03 6:01 AM, Tony J Ibbs (Tibs) (tony@lsl.co.uk) wrote:
> 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.

I wouldn't want to show any bias, or conflict of interest. :-)

Perhaps if recast as::

    Keyword arguments:

    - real: the real part (default 0.0)

    - imag: the imaginary part (default 0.0)

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

Please elaborate, with examples if possible.

> There's more I want to write on this - an updated version
> will follow at some time...

I look forward to it.

-- 
David Goodger    dgoodger@bigfoot.com    Open-source projects:
 - Python Docstring Processing System: http://docstring.sourceforge.net
 - reStructuredText: http://structuredtext.sourceforge.net
 - The Go Tools Project: http://gotools.sourceforge.net