Docstring from PEP 257 is filled incorrectly by Emacs

Docstring from PEP 257 is filled incorrectly by Emacs

[Radon Rosborough]

Hi all,

I recently noticed that Emacs fills an example docstring given [1] in
PEP 257 incorrectly. With `python-fill-docstring' 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
        ...

This seems erroneous to me since the value of `python-fill-docstring'
would suggest PEP 257 compliance. I also checked out the third-party
package `python-docstring' [2], and it has the same behavior. Do we
want to change the behavior of `python-docstring-fill', improve the
documentation to note this potentially confusing case, or leave it as
is?

Best,
Radon

[1]: https://www.python.org/dev/peps/pep-0257/#multi-line-docstrings
[2]: https://github.com/glyph/python-docstring-mode

Re: Docstring from PEP 257 is filled incorrectly by Emacs

[Clément Pit-Claudel]

On 2017-10-25 21:33, Radon Rosborough wrote:
> Do we want to change the behavior of `python-docstring-fill',\

Yes please :)

> improve the documentation to note this potentially confusing case,

Yes, in addition to the fix :)

> or leave it as is?

:/ Hopefully not

Clément.