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

Previous Next

Full log

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.