GNU bug report logs - #29003
[python.el] Docstring from PEP 257 is filled incorrectly by Emacs

Previous Next

Full log

View this message in rfc822 format

From: Radon Rosborough <radon.neon <at> gmail.com>
To: 29003 <at> debbugs.gnu.org
Subject: bug#29003: 25.3; Docstring from PEP 257 is filled incorrectly by Emacs
Date: Wed, 25 Oct 2017 19:08:47 -0700

I recently noticed that Emacs fills an example docstring given [1] in
PEP 257 incorrectly. With `python-fill-docstring-style' at its default
value of `pep-257', the following code sample:

    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 filled to:

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

There are two issues here: the extra newline added, and the unwrapping
of the keyword arguments. The extra newline can be suppressed by
changing the value of `python-fill-docstring-style', but the keyword
argument unwrapping does not appear to be suppressible. This seems
erroneous to me since the value of `python-fill-docstring' would suggest
PEP 257 compliance, i.e. the examples given in PEP 257 should not be a
affected by wrapping. (I also checked out the third-party package
`python-docstring' [2], and it has the same behavior.)

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.