[Python-checkins] Re: python/nondist/peps pep-0257.txt,1.6,1.7

[David Goodger]

[CVS]
>   The entire docstring is indented the same as the quotes at its first
> ! line (see example below).  Docstring processing tools will strip a
> ! uniform amount of indentation from the second and further lines of the
> ! docstring, equal to the minimum indentation of all non-blank lines
> ! after the first line of the docstring.  Relative indentation of later
> ! lines in the docstring is retained.  Any indentation on the first line
> ! of the docstring (i.e., before the first newline) is removed.

[GvR]
> I've seen many people write docstrings like this:
> 
>     def foo(self):
>         """
>     The foo algorithm.
> 
>     Blah, blah, blah.
>     """
> 
> This could be accommodated by using the first non-blank line rather
> than the first line.

The indentation of the first line is *not* being used.  I don't
think "the first non-blank line" is enough.  I saw a problem with
the old text:

    Docstring processing tools will strip an amount of indentation
    from the second and further lines of the docstring equal to the
    indentation of the first non-blank line after the first line of
    the docstring.

This could cause problems if too-literally applied in the unlikely
(but possible!) case of a docstring like this:

    def foo(self):
        """
            indented

        not indented
        """

The indentation of the first line is still intentionally ignored.
In both examples (yours & mine), each first line (up to the first
newline) is blank.  Perhaps that needs more explanation.

Is the new text unclear?  Does this issue deserve elaboration
in a new subsection?  Perhaps some well-commented code.  Even the
inspect.py docstring-trimming code has a subtle bug, in the case of
a docstring like this (also common):

    def foo():
        """ Space at start of the first line
        and the second line is flush-left.
        """

That first space ought to be removed.  I'll prepare a patch.

-- David Goodger