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

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 29003 in the body.
You can then email your comments to 29003 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Radon Rosborough <radon.neon <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 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.)

Message #10 received at 29003 <at> debbugs.gnu.org (full text, mbox):

From: charles <at> aurox.ch (Charles A. Roelli)
To: Radon Rosborough <radon.neon <at> gmail.com>
Cc: 29003 <at> debbugs.gnu.org
Subject: Re: bug#29003: 25.3;
 Docstring from PEP 257 is filled incorrectly by Emacs
Date: Thu, 26 Oct 2017 21:03:10 +0200

>        Keyword arguments:
>        real -- the real part (default 0.0)
>        imag -- the imaginary part (default 0.0)

I think all Emacs fill commands will fill this as one continous line,
unless you make the newlines between these lines "hard", as with M-x
use-hard-newlines (which is actually a minor mode, I think).

Message #13 received at 29003 <at> debbugs.gnu.org (full text, mbox):

From: Radon Rosborough <radon.neon <at> gmail.com>
To: "Charles A. Roelli" <charles <at> aurox.ch>
Cc: 29003 <at> debbugs.gnu.org
Subject: Re: bug#29003: 25.3;
 Docstring from PEP 257 is filled incorrectly by Emacs
Date: Thu, 26 Oct 2017 12:23:20 -0700

> I think all Emacs fill commands will fill this as one continous
> line,

As it currently stands, yes. That doesn't have to be the case,
however. For example, package `python-docstring' can understand reST
syntax, so that:

    def example_function():
        """Initialize engine.

        :param holes: Number of holes.
        :param rounds: Number of rounds.
        :param colors: Number of colors.

        :returns: Game engine instance.
        """
        pass

is not modified when filled. The question is whether the example given
by PEP 257 should be considered "standard" syntax for introducing
keyword arguments, and whether such syntax should be supported by
Emacs in a similar way to how `python-docstring' supports reST syntax.

Message #16 received at 29003 <at> debbugs.gnu.org (full text, mbox):

From: charles <at> aurox.ch (Charles A. Roelli)
To: Radon Rosborough <radon.neon <at> gmail.com>
Cc: 29003 <at> debbugs.gnu.org
Subject: Re: bug#29003: 25.3;
 Docstring from PEP 257 is filled incorrectly by Emacs
Date: Thu, 26 Oct 2017 21:41:51 +0200

It would be great if the example given was standard practice, but that
doesn't seem so.  The example also doesn't show how you might document
standard key arguments (without a default), which would be vital in
everyday usage.

Message #19 received at 29003 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: Radon Rosborough <radon.neon <at> gmail.com>
Cc: 29003 <at> debbugs.gnu.org, "Charles A. Roelli" <charles <at> aurox.ch>
Subject: Re: bug#29003: 25.3; Docstring from PEP 257 is filled incorrectly
 by Emacs
Date: Mon, 11 Nov 2019 03:43:49 +0100

Radon Rosborough <radon.neon <at> gmail.com> writes:

>> I think all Emacs fill commands will fill this as one continous
>> line,
>
> As it currently stands, yes. That doesn't have to be the case,
> however. For example, package `python-docstring' can understand reST
> syntax, so that:
>
>     def example_function():
>         """Initialize engine.
>
>         :param holes: Number of holes.
>         :param rounds: Number of rounds.
>         :param colors: Number of colors.
>
>         :returns: Game engine instance.
>         """
>         pass
>
> is not modified when filled. The question is whether the example given
> by PEP 257 should be considered "standard" syntax for introducing
> keyword arguments, and whether such syntax should be supported by
> Emacs in a similar way to how `python-docstring' supports reST syntax.

I think this should ideally be supported by Emacs, but it should be
configurable and disabled by default.

Best regards,
Stefan Kangas

Message #22 received at 29003 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: 29003 <at> debbugs.gnu.org, Radon Rosborough <radon.neon <at> gmail.com>,
 "Charles A. Roelli" <charles <at> aurox.ch>
Subject: Re: bug#29003: [python.el] Docstring from PEP 257 is filled
 incorrectly by Emacs
Date: Tue, 30 Nov 2021 15:56:59 +0100

Stefan Kangas <stefan <at> marxist.se> writes:

    > > > 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 modified when filled. The question is whether the example given
>> by PEP 257 should be considered "standard" syntax for introducing
>> keyword arguments, and whether such syntax should be supported by
>> Emacs in a similar way to how `python-docstring' supports reST syntax.
>
> I think this should ideally be supported by Emacs, but it should be
> configurable and disabled by default.

I think introducing these kinds of semantics in doc strings is
inherently brittle (unless really well-defined).  For instance,

      If this is a doc string, and then I
      pause -- using a double dash for a
      pause is common -- then we'd be filling
      things differently.

So I don't think changing the pep-257 style would be appropriate, and I
think adding a user option for this wouldn't receive much use.  So I'm
closing this bug report.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Previous Next

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