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

Please note: This is a static page, with minimal formatting, updated once a day.
Click here to see this page with the latest information and nicer formatting.
Package: emacs; Severity: minor; Reported by: Radon Rosborough <radon.neon@HIDDEN>; Keywords: wontfix; Done: Lars Ingebrigtsen <larsi@HIDDEN>; Maintainer for emacs is bug-gnu-emacs@HIDDEN.
bug closed, send any further explanations to 29003 <at> debbugs.gnu.org and Radon Rosborough <radon.neon@HIDDEN> Request was from Lars Ingebrigtsen <larsi@HIDDEN> to control <at> debbugs.gnu.org. Full text available.
Added tag(s) wontfix. Request was from Lars Ingebrigtsen <larsi@HIDDEN> to control <at> debbugs.gnu.org. Full text available.

Message received at 29003 <at> debbugs.gnu.org:


Received: (at 29003) by debbugs.gnu.org; 30 Nov 2021 14:57:10 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Tue Nov 30 09:57:10 2021
Received: from localhost ([127.0.0.1]:42107 helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.84_2)
	(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
	id 1ms4ZC-0002UM-3w
	for submit <at> debbugs.gnu.org; Tue, 30 Nov 2021 09:57:10 -0500
Received: from quimby.gnus.org ([95.216.78.240]:42430)
 by debbugs.gnu.org with esmtp (Exim 4.84_2)
 (envelope-from <larsi@HIDDEN>) id 1ms4ZA-0002U6-RD
 for 29003 <at> debbugs.gnu.org; Tue, 30 Nov 2021 09:57:09 -0500
DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnus.org;
 s=20200322; h=Content-Type:MIME-Version:Message-ID:In-Reply-To:Date:
 References:Subject:Cc:To:From:Sender:Reply-To:Content-Transfer-Encoding:
 Content-ID:Content-Description:Resent-Date:Resent-From:Resent-Sender:
 Resent-To:Resent-Cc:Resent-Message-ID:List-Id:List-Help:List-Unsubscribe:
 List-Subscribe:List-Post:List-Owner:List-Archive;
 bh=8QD0+RErsZLtN2oeGjCII7d+8vaACQePlh9dpY+r+98=; b=Uve+JN6VMEiWcoelEMRiQDdwbZ
 jxn5FwynfnJXgzpC5yzCx06mbNUfQEUHnCQfV17NVLUS6NofQN0b7i6pc6oi0Q8ZSfScr9MpHHbYc
 7WbbZAASJY9YdKnYKojPghTEhI0o4/BKh+32rS2crU9bLrgD3iDX9mMhPQpKXspS/sFc=;
Received: from [84.212.220.105] (helo=xo)
 by quimby.gnus.org with esmtpsa (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256)
 (Exim 4.92) (envelope-from <larsi@HIDDEN>)
 id 1ms4Z1-00079k-NI; Tue, 30 Nov 2021 15:57:02 +0100
From: Lars Ingebrigtsen <larsi@HIDDEN>
To: Stefan Kangas <stefan@HIDDEN>
Subject: Re: bug#29003: [python.el] Docstring from PEP 257 is filled
 incorrectly by Emacs
References: <CADB4rJGsp0dnK59ngewtvMndzRm2eNBB==auC4niccztBQ2_cA@HIDDEN>
 <m260b1bukx.fsf@HIDDEN>
 <CADB4rJHhKQDte_=8qckgyiWZ5A=odei_VuiSMhmhBXJeNnybiw@HIDDEN>
 <87tv7bqgii.fsf@HIDDEN>
X-Now-Playing: Normil Hawaiians's _More Wealth Than Money_: "An Old Standard"
Date: Tue, 30 Nov 2021 15:56:59 +0100
In-Reply-To: <87tv7bqgii.fsf@HIDDEN> (Stefan Kangas's message of "Mon, 11
 Nov 2019 03:43:49 +0100")
Message-ID: <87v909d744.fsf_-_@HIDDEN>
User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/29.0.50 (gnu/linux)
MIME-Version: 1.0
Content-Type: text/plain
X-Spam-Report: Spam detection software, running on the system "quimby.gnus.org",
 has NOT identified this incoming email as spam.  The original
 message has been attached to this so you can view it or label
 similar future email.  If you have any questions, see
 @@CONTACT_ADDRESS@@ for details.
 Content preview: Stefan Kangas <stefan@HIDDEN> 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) > > > "" [...] 
 Content analysis details:   (-2.9 points, 5.0 required)
 pts rule name              description
 ---- ---------------------- --------------------------------------------------
 -1.0 ALL_TRUSTED            Passed through trusted hosts only via SMTP
 -1.9 BAYES_00               BODY: Bayes spam probability is 0 to 1%
 [score: 0.0000]
X-Spam-Score: -2.3 (--)
X-Debbugs-Envelope-To: 29003
Cc: 29003 <at> debbugs.gnu.org, Radon Rosborough <radon.neon@HIDDEN>,
 "Charles A. Roelli" <charles@HIDDEN>
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.18
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
X-Spam-Score: -3.3 (---)

Stefan Kangas <stefan@HIDDEN> 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
Information forwarded to bug-gnu-emacs@HIDDEN:
bug#29003; Package emacs. Full text available.

Message received at 29003 <at> debbugs.gnu.org:


Received: (at 29003) by debbugs.gnu.org; 11 Nov 2019 02:43:59 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Sun Nov 10 21:43:59 2019
Received: from localhost ([127.0.0.1]:52955 helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.84_2)
	(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
	id 1iTzgN-0007ZF-Fz
	for submit <at> debbugs.gnu.org; Sun, 10 Nov 2019 21:43:59 -0500
Received: from host.gofardesign.uk ([208.79.239.190]:40772)
 by debbugs.gnu.org with esmtp (Exim 4.84_2)
 (envelope-from <stefan@HIDDEN>) id 1iTzgL-0007Yy-Iw
 for 29003 <at> debbugs.gnu.org; Sun, 10 Nov 2019 21:43:58 -0500
DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=marxist.se; 
 s=default;
 h=Content-Type:MIME-Version:Message-ID:Date:References:
 In-Reply-To:Subject:Cc:To:From:Sender:Reply-To:Content-Transfer-Encoding:
 Content-ID:Content-Description:Resent-Date:Resent-From:Resent-Sender:
 Resent-To:Resent-Cc:Resent-Message-ID:List-Id:List-Help:List-Unsubscribe:
 List-Subscribe:List-Post:List-Owner:List-Archive;
 bh=vdeBNDW7H22Fub+9yzjqMu7CFKZb/o/gj9eQkU2ISms=; b=jrQyw8xrk9FQXeN8DDb5GKtcx+
 kSRlXx4bnwOboVptfFPnZL01nHYxuyqLzwFEc1HOEKk22aw452YiEZ8dIXsFnI0g+3828Wjz8W3UF
 3bj80A7zl50OZfXFPaNJ+82oqwdm+NzsMsss/sZniQsNpp6fOZVkPkG0bRhNtoAiiAfg=;
Received: from h-70-69.a785.priv.bahnhof.se ([155.4.70.69]:35602
 helo=localhost)
 by host.gofardesign.uk with esmtpsa (TLSv1.2:ECDHE-RSA-AES256-GCM-SHA384:256)
 (Exim 4.92) (envelope-from <stefan@HIDDEN>)
 id 1iTzgF-0007g4-68; Sun, 10 Nov 2019 20:43:51 -0600
From: Stefan Kangas <stefan@HIDDEN>
To: Radon Rosborough <radon.neon@HIDDEN>
Subject: Re: bug#29003: 25.3; Docstring from PEP 257 is filled incorrectly
 by Emacs
In-Reply-To: <CADB4rJHhKQDte_=8qckgyiWZ5A=odei_VuiSMhmhBXJeNnybiw@HIDDEN>
 (Radon Rosborough's message of "Thu, 26 Oct 2017 12:23:20 -0700")
References: <CADB4rJGsp0dnK59ngewtvMndzRm2eNBB==auC4niccztBQ2_cA@HIDDEN>
 <m260b1bukx.fsf@HIDDEN>
 <CADB4rJHhKQDte_=8qckgyiWZ5A=odei_VuiSMhmhBXJeNnybiw@HIDDEN>
User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.0.50 (gnu/linux)
Date: Mon, 11 Nov 2019 03:43:49 +0100
Message-ID: <87tv7bqgii.fsf@HIDDEN>
MIME-Version: 1.0
Content-Type: text/plain
X-OutGoing-Spam-Status: No, score=-1.0
X-AntiAbuse: This header was added to track abuse,
 please include it with any abuse report
X-AntiAbuse: Primary Hostname - host.gofardesign.uk
X-AntiAbuse: Original Domain - debbugs.gnu.org
X-AntiAbuse: Originator/Caller UID/GID - [47 12] / [47 12]
X-AntiAbuse: Sender Address Domain - marxist.se
X-Get-Message-Sender-Via: host.gofardesign.uk: authenticated_id:
 stefan@HIDDEN
X-Authenticated-Sender: host.gofardesign.uk: stefan@HIDDEN
X-Source: 
X-Source-Args: 
X-Source-Dir: 
X-Spam-Score: -0.0 (/)
X-Debbugs-Envelope-To: 29003
Cc: 29003 <at> debbugs.gnu.org, "Charles A. Roelli" <charles@HIDDEN>
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.18
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
X-Spam-Score: -1.0 (-)

Radon Rosborough <radon.neon@HIDDEN> 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
Information forwarded to bug-gnu-emacs@HIDDEN:
bug#29003; Package emacs. Full text available.

Message received at 29003 <at> debbugs.gnu.org:


Received: (at 29003) by debbugs.gnu.org; 26 Oct 2017 19:40:55 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Thu Oct 26 15:40:55 2017
Received: from localhost ([127.0.0.1]:35526 helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.84_2)
	(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
	id 1e7o1O-0005O5-VH
	for submit <at> debbugs.gnu.org; Thu, 26 Oct 2017 15:40:55 -0400
Received: from sinyavsky.aurox.ch ([37.35.109.145]:32794)
 by debbugs.gnu.org with esmtp (Exim 4.84_2)
 (envelope-from <charles@HIDDEN>) id 1e7o1M-0005Nr-0N
 for 29003 <at> debbugs.gnu.org; Thu, 26 Oct 2017 15:40:53 -0400
Received: from sinyavsky.aurox.ch (sinyavsky.aurox.ch [127.0.0.1])
 by sinyavsky.aurox.ch (Postfix) with ESMTP id 346A422597
 for <29003 <at> debbugs.gnu.org>; Thu, 26 Oct 2017 19:33:53 +0000 (UTC)
Authentication-Results: sinyavsky.aurox.ch (amavisd-new);
 dkim=pass (1024-bit key) reason="pass (just generated, assumed good)"
 header.d=aurox.ch
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=aurox.ch; h=
 references:subject:subject:in-reply-to:to:from:from:message-id
 :date:date; s=dkim; t=1509046431; x=1509910432; bh=Ohu83S1l8u+vj
 BU+LauF1uVN8dSiK7rxamK2vnPDTNY=; b=aCDb7p1fDR4Fmy7MdVPFOfuSjGnbj
 trPKyp01QAxLXDPsBiETZ+75KS9KHjG7x8X4d/CZ2lursRsHZbAGFK+ep36M+AOW
 yhe7K4PtuCXpoKVN94pRqDTPGLn5XkI7fA5FrjXNDjNMsi0oC0mzqcV0xTPen+Fu
 ABO8e6hd3kCxV4=
X-Virus-Scanned: Debian amavisd-new at test.virtualizor.com
Received: from sinyavsky.aurox.ch ([127.0.0.1])
 by sinyavsky.aurox.ch (sinyavsky.aurox.ch [127.0.0.1]) (amavisd-new,
 port 10026) with ESMTP id yln7aVLpwHEL for <29003 <at> debbugs.gnu.org>;
 Thu, 26 Oct 2017 19:33:51 +0000 (UTC)
Received: from gray (125.85.192.178.dynamic.wline.res.cust.swisscom.ch
 [178.192.85.125])
 by sinyavsky.aurox.ch (Postfix) with ESMTPSA id 931AD22564;
 Thu, 26 Oct 2017 19:33:51 +0000 (UTC)
Date: Thu, 26 Oct 2017 21:41:51 +0200
Message-Id: <m24lqlbssg.fsf@HIDDEN>
From: charles@HIDDEN (Charles A. Roelli)
To: Radon Rosborough <radon.neon@HIDDEN>
In-reply-to: <CADB4rJHhKQDte_=8qckgyiWZ5A=odei_VuiSMhmhBXJeNnybiw@HIDDEN>
 (message from Radon Rosborough on Thu, 26 Oct 2017 12:23:20 -0700)
Subject: Re: bug#29003: 25.3;
 Docstring from PEP 257 is filled incorrectly by Emacs
References: <CADB4rJGsp0dnK59ngewtvMndzRm2eNBB==auC4niccztBQ2_cA@HIDDEN>
 <m260b1bukx.fsf@HIDDEN>
 <CADB4rJHhKQDte_=8qckgyiWZ5A=odei_VuiSMhmhBXJeNnybiw@HIDDEN>
X-Spam-Score: -2.3 (--)
X-Debbugs-Envelope-To: 29003
Cc: 29003 <at> debbugs.gnu.org
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.18
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
X-Spam-Score: -2.3 (--)

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.
Information forwarded to bug-gnu-emacs@HIDDEN:
bug#29003; Package emacs. Full text available.

Message received at 29003 <at> debbugs.gnu.org:


Received: (at 29003) by debbugs.gnu.org; 26 Oct 2017 19:24:08 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Thu Oct 26 15:24:08 2017
Received: from localhost ([127.0.0.1]:35512 helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.84_2)
	(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
	id 1e7nlA-000503-EX
	for submit <at> debbugs.gnu.org; Thu, 26 Oct 2017 15:24:08 -0400
Received: from mail-lf0-f42.google.com ([209.85.215.42]:53918)
 by debbugs.gnu.org with esmtp (Exim 4.84_2)
 (envelope-from <radon.neon@HIDDEN>) id 1e7nl9-0004zc-C8
 for 29003 <at> debbugs.gnu.org; Thu, 26 Oct 2017 15:24:07 -0400
Received: by mail-lf0-f42.google.com with SMTP id l23so4931992lfk.10
 for <29003 <at> debbugs.gnu.org>; Thu, 26 Oct 2017 12:24:07 -0700 (PDT)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025;
 h=mime-version:in-reply-to:references:from:date:message-id:subject:to
 :cc; bh=avyjOESxlhvAwVzD5rbol2YkzfHdeOxhw5c5g+4bZtY=;
 b=UsozViaYufN/ePVezwvSMCXcUcK0JzCwLD9rKiUpBKBHTkt33+FE7ACzSMYngZrMsW
 VD0evFzT3jnfgs1o1X0HNV/I+NXBGGAEWLkJe7DicX6ErVC1CrNDr/tpc7US4YDj3knW
 kcjrMQU7Xb3x1Vfbi2P7HgyuU+WLYOWwFw4xV+LMb65PqjfXArcjZKdoeRYKFUOJaRZ1
 SwVgxgyoLov/ybl5Ln3lWvThc1NMK/LKGxoal2/WFSL3II20OSEhj9k7rQHGrTT/EEIc
 wfxK8Le7H3FNXqzgGGkReuO2myWn6PdcPsR5xQkpG6NakYrtXJn7JO2qCQlgpPxd9eAo
 KQrg==
X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
 d=1e100.net; s=20161025;
 h=x-gm-message-state:mime-version:in-reply-to:references:from:date
 :message-id:subject:to:cc;
 bh=avyjOESxlhvAwVzD5rbol2YkzfHdeOxhw5c5g+4bZtY=;
 b=llAnmq3yyvov24OgjtPGmd+oXA+VLGrM4+OfC6hR9Kl3VruyBcYKIsero+hAy5Gpdg
 GiH4D/L6UpFnUDm7HFB1mtnfjj2uDzOvjXL8mg+LtjnJF4EJWmv+IOqp7M7YB+Pspqg2
 kOCR4u2VPd5Dd2AkcA0RCrJhjgHXbvO4AcN39Q27srq41RBfwnNSdhgVh0MTpHl4A0qU
 G88dkW7myD2d+qiwRpY1jWaaqTgKxWKCTtRSvB1C0n48KmSD+Ouf2CXhRs+wSnndGtW1
 lyOBf193wDMq1IkRt+VnGILlEnnGw9sWcPBlczsyFgvvtJfkNP1gzlD05GjKr/3JsVgt
 ti0g==
X-Gm-Message-State: AMCzsaXJn/m0h7D8dRn8VxOBC2KTRennaXpsQVfwOI79524hElKvq+jE
 TePuOc4YaCZDprzwHdfgVTuQzb3mhovP2N656IfXyWLN
X-Google-Smtp-Source: ABhQp+TkwlBxl4PX5UjM7C27VpOCzAcZf+wpKZFg8OS1fxtsFoiXQxhhnv28Nxw9E5zGLRKVTehnS5n1SoMOIdQS/AM=
X-Received: by 10.25.87.66 with SMTP id l63mr8262266lfb.101.1509045841021;
 Thu, 26 Oct 2017 12:24:01 -0700 (PDT)
MIME-Version: 1.0
Received: by 10.25.208.10 with HTTP; Thu, 26 Oct 2017 12:23:20 -0700 (PDT)
In-Reply-To: <m260b1bukx.fsf@HIDDEN>
References: <CADB4rJGsp0dnK59ngewtvMndzRm2eNBB==auC4niccztBQ2_cA@HIDDEN>
 <m260b1bukx.fsf@HIDDEN>
From: Radon Rosborough <radon.neon@HIDDEN>
Date: Thu, 26 Oct 2017 12:23:20 -0700
Message-ID: <CADB4rJHhKQDte_=8qckgyiWZ5A=odei_VuiSMhmhBXJeNnybiw@HIDDEN>
Subject: Re: bug#29003: 25.3;
 Docstring from PEP 257 is filled incorrectly by Emacs
To: "Charles A. Roelli" <charles@HIDDEN>
Content-Type: text/plain; charset="UTF-8"
X-Spam-Score: 0.5 (/)
X-Debbugs-Envelope-To: 29003
Cc: 29003 <at> debbugs.gnu.org
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.18
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
X-Spam-Score: 0.5 (/)

> 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.
Information forwarded to bug-gnu-emacs@HIDDEN:
bug#29003; Package emacs. Full text available.

Message received at 29003 <at> debbugs.gnu.org:


Received: (at 29003) by debbugs.gnu.org; 26 Oct 2017 19:02:13 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Thu Oct 26 15:02:13 2017
Received: from localhost ([127.0.0.1]:35485 helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.84_2)
	(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
	id 1e7nPx-0004UG-Je
	for submit <at> debbugs.gnu.org; Thu, 26 Oct 2017 15:02:13 -0400
Received: from sinyavsky.aurox.ch ([37.35.109.145]:60975)
 by debbugs.gnu.org with esmtp (Exim 4.84_2)
 (envelope-from <charles@HIDDEN>) id 1e7nPv-0004U0-Oo
 for 29003 <at> debbugs.gnu.org; Thu, 26 Oct 2017 15:02:12 -0400
Received: from sinyavsky.aurox.ch (sinyavsky.aurox.ch [127.0.0.1])
 by sinyavsky.aurox.ch (Postfix) with ESMTP id 3991F22587
 for <29003 <at> debbugs.gnu.org>; Thu, 26 Oct 2017 18:55:11 +0000 (UTC)
Authentication-Results: sinyavsky.aurox.ch (amavisd-new);
 dkim=pass (1024-bit key) reason="pass (just generated, assumed good)"
 header.d=aurox.ch
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=aurox.ch; h=
 references:subject:subject:in-reply-to:to:from:from:message-id
 :date:date; s=dkim; t=1509044110; x=1509908111; bh=ERbU0RgmO7cI6
 c8dcQdLgawH3gnJFjCx9aRTtCdqrJw=; b=q99vDjSIEUgCDGz49JWJZVYJutVhG
 gyw7VXb2H2gNnqQulgeFF4rGdi6wdIKoOnAEJgUWkYgudrkYAqPRgUjxHhYVDRW4
 PRsiwJrE/e1WUEmds7xEgIvViFqGy76Y5wfPo3ah7jOoW5SFCQGQNaoFzC1+Idx2
 ebiJKQRnfYmCEU=
X-Virus-Scanned: Debian amavisd-new at test.virtualizor.com
Received: from sinyavsky.aurox.ch ([127.0.0.1])
 by sinyavsky.aurox.ch (sinyavsky.aurox.ch [127.0.0.1]) (amavisd-new,
 port 10026) with ESMTP id Y-IW8U05wQzF for <29003 <at> debbugs.gnu.org>;
 Thu, 26 Oct 2017 18:55:10 +0000 (UTC)
Received: from gray (125.85.192.178.dynamic.wline.res.cust.swisscom.ch
 [178.192.85.125])
 by sinyavsky.aurox.ch (Postfix) with ESMTPSA id 5B70A22564;
 Thu, 26 Oct 2017 18:55:10 +0000 (UTC)
Date: Thu, 26 Oct 2017 21:03:10 +0200
Message-Id: <m260b1bukx.fsf@HIDDEN>
From: charles@HIDDEN (Charles A. Roelli)
To: Radon Rosborough <radon.neon@HIDDEN>
In-reply-to: <CADB4rJGsp0dnK59ngewtvMndzRm2eNBB==auC4niccztBQ2_cA@HIDDEN>
 (message from Radon Rosborough on Wed, 25 Oct 2017 19:08:47 -0700)
Subject: Re: bug#29003: 25.3;
 Docstring from PEP 257 is filled incorrectly by Emacs
References: <CADB4rJGsp0dnK59ngewtvMndzRm2eNBB==auC4niccztBQ2_cA@HIDDEN>
X-Spam-Score: -2.3 (--)
X-Debbugs-Envelope-To: 29003
Cc: 29003 <at> debbugs.gnu.org
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.18
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
X-Spam-Score: -2.3 (--)

>        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).
Information forwarded to bug-gnu-emacs@HIDDEN:
bug#29003; Package emacs. Full text available.
Changed bug title to '[python.el] Docstring from PEP 257 is filled incorrectly by Emacs' from '25.3; Docstring from PEP 257 is filled incorrectly by Emacs' Request was from Noam Postavsky <npostavs@HIDDEN> to control <at> debbugs.gnu.org. Full text available.

Message received at submit <at> debbugs.gnu.org:


Received: (at submit) by debbugs.gnu.org; 26 Oct 2017 02:09:39 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Wed Oct 25 22:09:39 2017
Received: from localhost ([127.0.0.1]:33770 helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.84_2)
	(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
	id 1e7Xc3-0003qf-5C
	for submit <at> debbugs.gnu.org; Wed, 25 Oct 2017 22:09:39 -0400
Received: from eggs.gnu.org ([208.118.235.92]:34184)
 by debbugs.gnu.org with esmtp (Exim 4.84_2)
 (envelope-from <radon.neon@HIDDEN>) id 1e7Xc1-0003qQ-7v
 for submit <at> debbugs.gnu.org; Wed, 25 Oct 2017 22:09:37 -0400
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
 (envelope-from <radon.neon@HIDDEN>) id 1e7Xbv-0006Bh-9I
 for submit <at> debbugs.gnu.org; Wed, 25 Oct 2017 22:09:31 -0400
X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org
X-Spam-Level: 
X-Spam-Status: No, score=0.0 required=5.0 tests=BAYES_20,FREEMAIL_FROM,
 T_DKIM_INVALID autolearn=disabled version=3.3.2
Received: from lists.gnu.org ([2001:4830:134:3::11]:58482)
 by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_256_CBC_SHA1:32)
 (Exim 4.71) (envelope-from <radon.neon@HIDDEN>)
 id 1e7Xbv-0006Bc-5m
 for submit <at> debbugs.gnu.org; Wed, 25 Oct 2017 22:09:31 -0400
Received: from eggs.gnu.org ([2001:4830:134:3::10]:53388)
 by lists.gnu.org with esmtp (Exim 4.71)
 (envelope-from <radon.neon@HIDDEN>) id 1e7Xbu-0001Y3-9X
 for bug-gnu-emacs@HIDDEN; Wed, 25 Oct 2017 22:09:31 -0400
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
 (envelope-from <radon.neon@HIDDEN>) id 1e7Xbt-0006Au-Go
 for bug-gnu-emacs@HIDDEN; Wed, 25 Oct 2017 22:09:30 -0400
Received: from mail-lf0-x22b.google.com ([2a00:1450:4010:c07::22b]:45002)
 by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16)
 (Exim 4.71) (envelope-from <radon.neon@HIDDEN>)
 id 1e7Xbt-0006Ae-8Z
 for bug-gnu-emacs@HIDDEN; Wed, 25 Oct 2017 22:09:29 -0400
Received: by mail-lf0-x22b.google.com with SMTP id 75so2031820lfx.1
 for <bug-gnu-emacs@HIDDEN>; Wed, 25 Oct 2017 19:09:29 -0700 (PDT)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025;
 h=mime-version:from:date:message-id:subject:to;
 bh=a4ds1HGfnm2QNTJGn71O6Ohv7+EUQFzxjooq1qBJeUQ=;
 b=TXDz8qltRhnLHuGUwcBAeZKSmF38jOhaCdvfHpiwQOohtg5CKGWpo/PKEvBmtKW8Pn
 cU3q3PsJMBGNeD+5w0fKUAI4PLBKxtVNeNgG2yUa32/n1AKTfkaW0wzKpt/L8klJTEO8
 NPiMryKkYhjtMEvjV1WmUDo4kqYan2GIsx/k3mGyLVfZXW3ontjipru2e5Jvf++6NQob
 7sXpP99t6U+/XwQZIxl1zn3wua/shwOet3rofWT9OzTeg5PvTaDxmQoNVJa+b+y6W8EB
 iVdFshT6a/MuOGLEh5Zho4daUYpxn9ehwGsTcrgGgSi/yVdje7x3odyxCShWK3I/xyRr
 FmvQ==
X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
 d=1e100.net; s=20161025;
 h=x-gm-message-state:mime-version:from:date:message-id:subject:to;
 bh=a4ds1HGfnm2QNTJGn71O6Ohv7+EUQFzxjooq1qBJeUQ=;
 b=fAaVjcIARYXPi4vWUbpFUxkQf3ox2ORrnVsJ/CJpwxLaxRB9bWWbdCK/ppmA8FeTnj
 EJNKd3v1Kv+d94dS51mlcSZcPlIWupUWaU5YPHhxhzX6onRNFkesTWcJlxvL6X5/kKyF
 IYwap5OsAr/KhDs1ykrd5Ulx+JjrpYAXdHdIOcXELd5zfuXk+lfFfTC7k7NebE4dPE9j
 HSrxCGpoMPLATcuGHBEKxsS4OHzGkQOBMMC4Mktw6v/8LJImWGES+KpUdJ54IglUgylm
 U/VVuCcMdWrjwdnZuK59DdYxuIPv+6eemrwQ4XW0YUe/aqU9imG4qsDfPfOnd3xsm3Pa
 Dw6A==
X-Gm-Message-State: AMCzsaUk2olmp5M1x7uTvMkRSw6IJHI2CnNqQq8UMwmyyEzHpkexgeYm
 0/TIQEY3PFPHH7WYy9is5litgi0Dsn3+ZFl2ySnabQ==
X-Google-Smtp-Source: ABhQp+QHwWD0OPS52Z+3ByrYal7Zgiao34LELkWG7hmw5DUILpFRT6PZ8fIqHElQ838R+MhoGO7G3oneLYnusElT6Rk=
X-Received: by 10.46.25.132 with SMTP id 4mr8864111ljz.145.1508983767658; Wed,
 25 Oct 2017 19:09:27 -0700 (PDT)
MIME-Version: 1.0
Received: by 10.25.208.10 with HTTP; Wed, 25 Oct 2017 19:08:47 -0700 (PDT)
From: Radon Rosborough <radon.neon@HIDDEN>
Date: Wed, 25 Oct 2017 19:08:47 -0700
Message-ID: <CADB4rJGsp0dnK59ngewtvMndzRm2eNBB==auC4niccztBQ2_cA@HIDDEN>
Subject: 25.3; Docstring from PEP 257 is filled incorrectly by Emacs
To: bug-gnu-emacs@HIDDEN
Content-Type: text/plain; charset="UTF-8"
X-detected-operating-system: by eggs.gnu.org: Genre and OS details not
 recognized.
X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x
X-Received-From: 2001:4830:134:3::11
X-Spam-Score: -4.0 (----)
X-Debbugs-Envelope-To: submit
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.18
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
X-Spam-Score: -4.0 (----)

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.)
Acknowledgement sent to Radon Rosborough <radon.neon@HIDDEN>:
New bug report received and forwarded. Copy sent to bug-gnu-emacs@HIDDEN. Full text available.
Report forwarded to bug-gnu-emacs@HIDDEN:
bug#29003; Package emacs. Full text available.
Please note: This is a static page, with minimal formatting, updated once a day.
Click here to see this page with the latest information and nicer formatting.
Last modified: Tue, 30 Nov 2021 15:00:01 UTC

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