From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Mattias =?UTF-8?Q?Engdeg=C3=A5rd?= Newsgroups: gmane.emacs.bugs Subject: bug#69387: 30.0.50; A string shouldn't be both a docstring and a return value Date: Wed, 6 Mar 2024 12:44:19 +0100 Message-ID: <01974A21-25DA-4445-BDE7-A022AF1D1BF8@gmail.com> References: <2D08AD76-59F7-41BE-9363-96677967034A@gmail.com> <4FCE8B7D-17D7-44E8-A764-A6047209CBE1@gmail.com> <86bk7um4v1.fsf@gnu.org> <74101BB1-B82C-4F6C-8AB1-47A131BC90E6@gmail.com> <86r0golmdg.fsf@gnu.org> Mime-Version: 1.0 (Mac OS X Mail 14.0 \(3654.120.0.1.15\)) Content-Type: multipart/mixed; boundary="Apple-Mail=_D7AB377B-44E6-48B3-B7C6-B3B28CA95FFE" Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="9707"; mail-complaints-to="usenet@ciao.gmane.io" Cc: philipk@posteo.net, 69387@debbugs.gnu.org, monnier@iro.umontreal.ca To: Eli Zaretskii Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Wed Mar 06 12:45:51 2024 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1rhpiY-0002Jf-TH for geb-bug-gnu-emacs@m.gmane-mx.org; Wed, 06 Mar 2024 12:45:51 +0100 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1rhpiK-0003S0-Pe; Wed, 06 Mar 2024 06:45:36 -0500 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1rhpiG-0003OV-4I for bug-gnu-emacs@gnu.org; Wed, 06 Mar 2024 06:45:34 -0500 Original-Received: from debbugs.gnu.org ([2001:470:142:5::43]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1rhpiF-0005qP-Pd for bug-gnu-emacs@gnu.org; Wed, 06 Mar 2024 06:45:31 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1rhpik-0006Sl-Hw for bug-gnu-emacs@gnu.org; Wed, 06 Mar 2024 06:46:02 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Mattias =?UTF-8?Q?Engdeg=C3=A5rd?= Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Wed, 06 Mar 2024 11:46:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 69387 X-GNU-PR-Package: emacs Original-Received: via spool by 69387-submit@debbugs.gnu.org id=B69387.170972556024835 (code B ref 69387); Wed, 06 Mar 2024 11:46:02 +0000 Original-Received: (at 69387) by debbugs.gnu.org; 6 Mar 2024 11:46:00 +0000 Original-Received: from localhost ([127.0.0.1]:49905 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1rhpii-0006SV-FI for submit@debbugs.gnu.org; Wed, 06 Mar 2024 06:46:00 -0500 Original-Received: from mail-lf1-f50.google.com ([209.85.167.50]:61670) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1rhpif-0006SH-V1 for 69387@debbugs.gnu.org; Wed, 06 Mar 2024 06:45:58 -0500 Original-Received: by mail-lf1-f50.google.com with SMTP id 2adb3069b0e04-512f3e75391so1752410e87.2 for <69387@debbugs.gnu.org>; Wed, 06 Mar 2024 03:45:27 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1709725461; x=1710330261; darn=debbugs.gnu.org; h=references:to:cc:in-reply-to:date:subject:mime-version:message-id :from:sender:from:to:cc:subject:date:message-id:reply-to; bh=Lps5FllsUJz05MywvWK1YT9C/pAfh4flk/9oSnn49qc=; b=V/3Yyo5/PJ4inUDSS66bH/xQkF622u6CpCOXP2FcCDjV20yoYcfiCfo/+N/lzs6fsN qr506m0Z+wmC2ZW0/nu2QS9QusAQOsI+1plVUAWWtqIPrvcMTpfkvzlUcgOiZznGlOzt emkbwFy/p/7xTc8319rB7iGdE1nHT7zOTqCPRpGhSOK9XPieVZ05uONTFydQdWsPuGU7 fPyJoCCFnBUa8HXfsTJhaYu1GZ7yohECj5q2Sy8BTnzJLkiMCCK33gxy3IEAlhdpEd2g ZV73ma/4D5XPcCPqwc5iutEOlXJejdu45zazeg9I5aEndUMsymG2ajOM30xyDUDJ8vIa 4XCA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1709725461; x=1710330261; h=references:to:cc:in-reply-to:date:subject:mime-version:message-id :from:sender:x-gm-message-state:from:to:cc:subject:date:message-id :reply-to; bh=Lps5FllsUJz05MywvWK1YT9C/pAfh4flk/9oSnn49qc=; b=YOd475fr0lhbb4pnONgISEPzn84eFEC9HCDB0pwjJsLYB8L5GLEQHVj/p1d1meURno pBKw5B+mMK2LX/FUC/JNWp50zgLirCPUUfHjJtAOjIZjXtG/+E0fjL4Lt6FJAPy0oWDy j8ARqlnloOZO14KVYWHAp/YGNqZuMRvmwSR20NOqmtd6M2BkaKhGNSsF4Kgye5Fq/Qqv cgeCnvO8X9hcLuVhT99gPGN26hfMd/eV6yud0RqI/ljcpw5OcDaO4SAIB3ABuTnlAJ5J /XGfbVF1UlLvW2R4GShIbCIPHF28akOwE/fTaEynv6JG/r7TYtJu2GajuB3ue3U+xqG4 bLfg== X-Forwarded-Encrypted: i=1; AJvYcCVgyE25w4twGHz4xAM4VpUUXzvmIRDxBOEh8Q98Ouu96To42ykjCNoU7j9YhqqOrKTmI5eJDyK2Qj8TelT5zycTIyitY1Q= X-Gm-Message-State: AOJu0Yzw7vK7BZxI2SBDJ7i+6Y3CGAICaMR3Fbqojva3H7I3AWo9FG+5 CUlbFh8GedSzHgiwylQFuy40OwhzZ5yRO9cMgmghQBvn0Irj2ppR X-Google-Smtp-Source: AGHT+IGk3ssBVHzeRCEcwdFCpvriMUpxBgQmtWbelZ/aWt9AZwZ9nZobuLDfWHy0JMAVuNDuej88Zg== X-Received: by 2002:ac2:5592:0:b0:513:5eee:3dab with SMTP id v18-20020ac25592000000b005135eee3dabmr838599lfg.8.1709725460846; Wed, 06 Mar 2024 03:44:20 -0800 (PST) Original-Received: from smtpclient.apple (c80-217-1-132.bredband.tele2.se. [80.217.1.132]) by smtp.gmail.com with ESMTPSA id c11-20020a19760b000000b005131e4346e3sm2579727lff.180.2024.03.06.03.44.20 (version=TLS1_2 cipher=ECDHE-ECDSA-AES128-GCM-SHA256 bits=128/128); Wed, 06 Mar 2024 03:44:20 -0800 (PST) In-Reply-To: <86r0golmdg.fsf@gnu.org> X-Mailer: Apple Mail (2.3654.120.0.1.15) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Xref: news.gmane.io gmane.emacs.bugs:281107 Archived-At: --Apple-Mail=_D7AB377B-44E6-48B3-B7C6-B3B28CA95FFE Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset=us-ascii 5 mars 2024 kl. 16.38 skrev Eli Zaretskii : > Thanks, but please always remember to end the heading lines in NEWS > with a period. Thank you, corrected in the patch. I'm rowing back on the warning; it's probably more annoying than = detecting actual errors, so it's been dropped from the patch. --Apple-Mail=_D7AB377B-44E6-48B3-B7C6-B3B28CA95FFE Content-Disposition: attachment; filename=0001-Use-single-string-literal-as-return-value-not-doc-st.patch Content-Type: application/octet-stream; x-unix-mode=0644; name="0001-Use-single-string-literal-as-return-value-not-doc-st.patch" Content-Transfer-Encoding: quoted-printable =46rom=20dd2aeed849d4f3c72ab37f942700f8f79f1439c2=20Mon=20Sep=2017=20= 00:00:00=202001=0AFrom:=20=3D?UTF-8?q?Mattias=3D20Engdeg=3DC3=3DA5rd?=3D=20= =0ADate:=20Wed,=206=20Mar=202024=2012:03:06=20+0100=0A= Subject:=20[PATCH]=20Use=20single=20string=20literal=20as=20return=20= value,=20not=20doc=20string=0A=0AA=20function=20or=20macro=20body=20= consisting=20of=20a=20single=20string=20literal=20now=20only=0Auses=20it=20= as=20a=20return=20value.=20=20Previously,=20it=20was=20used=20as=20a=20= doc=20string=20as=0Awell=20which=20was=20never=20what=20the=20programmer=20= intended=20and=20had=20some=0Ainconvenient=20consequences=20(bug#69387).=0A= =0A*=20lisp/emacs-lisp/bytecomp.el=20(byte-compile-lambda):=0ADon't=20= use=20a=20lone=20string=20literal=20as=20doc=20string.=0A*=20= test/lisp/emacs-lisp/bytecomp-resources/warn-wide-docstring-defun.el=0A= (foo):=20Update=20docstring=20warning=20test.=0A*=20= doc/lispref/functions.texi=20(Function=20Documentation):=20Update=20= manual.=0A*=20etc/NEWS:=20Announce=20the=20change.=0A---=0A=20= doc/lispref/functions.texi=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20= =20=20=20=20=20=20=20|=2013=20++++++-------=0A=20etc/NEWS=20=20=20=20=20=20= =20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20= =20=20=20=20=20=20=20=20=20=20|=2016=20++++++++++++++++=0A=20= lisp/emacs-lisp/bytecomp.el=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20= =20=20=20=20=20=20|=20=209=20++++-----=0A=20= .../warn-wide-docstring-defun.el=20=20=20=20=20=20=20=20=20=20=20=20=20=20= =20=20=20|=20=203=20++-=0A=204=20files=20changed,=2028=20insertions(+),=20= 13=20deletions(-)=0A=0Adiff=20--git=20a/doc/lispref/functions.texi=20= b/doc/lispref/functions.texi=0Aindex=20344b3ff3a50..ff635fc54b2=20100644=0A= ---=20a/doc/lispref/functions.texi=0A+++=20b/doc/lispref/functions.texi=0A= @@=20-498,13=20+498,12=20@@=20Function=20Documentation=0A=20nice=20in=20= the=20source=20code=20will=20look=20ugly=20when=20displayed=20by=20the=20= help=0A=20commands.=0A=20=0A-=20=20You=20may=20wonder=20how=20the=20= documentation=20string=20could=20be=20optional,=20since=0A-there=20are=20= required=20components=20of=20the=20function=20that=20follow=20it=20(the=20= body).=0A-Since=20evaluation=20of=20a=20string=20returns=20that=20= string,=20without=20any=20side=20effects,=0A-it=20has=20no=20effect=20if=20= it=20is=20not=20the=20last=20form=20in=20the=20body.=20=20Thus,=20in=0A= -practice,=20there=20is=20no=20confusion=20between=20the=20first=20form=20= of=20the=20body=20and=20the=0A-documentation=20string;=20if=20the=20only=20= body=20form=20is=20a=20string=20then=20it=20serves=20both=0A-as=20the=20= return=20value=20and=20as=20the=20documentation.=0A+=20=20A=20= documentation=20string=20must=20always=20be=20followed=20by=20at=20least=20= one=20Lisp=0A+expression;=20otherwise,=20it=20is=20not=20a=20= documentation=20string=20at=20all=20but=20the=0A+single=20expression=20= of=20the=20body=20and=20used=20as=20the=20return=20value.=0A+When=20= there=20is=20no=20meaningful=20value=20to=20return=20from=20a=20= function,=20it=20is=0A+standard=20practice=20to=20return=20@code{nil}=20= by=20adding=20it=20after=20the=0A+documentation=20string.=0A=20=0A=20=20=20= The=20last=20line=20of=20the=20documentation=20string=20can=20specify=20= calling=0A=20conventions=20different=20from=20the=20actual=20function=20= arguments.=20=20Write=0Adiff=20--git=20a/etc/NEWS=20b/etc/NEWS=0Aindex=20= fd957fdb115..73faeb20126=20100644=0A---=20a/etc/NEWS=0A+++=20b/etc/NEWS=0A= @@=20-1805,6=20+1805,22=20@@=20Tree-sitter=20conditionally=20sets=20= 'forward-sexp-function'=20for=20major=20modes=0A=20that=20have=20defined=20= 'sexp'=20in=20'treesit-thing-settings'=20to=20enable=0A=20sexp-related=20= motion=20commands.=0A=20=0A++++=0A+**=20Returned=20strings=20are=20never=20= docstrings.=0A+Functions=20and=20macros=20whose=20bodies=20consist=20of=20= a=20single=20string=20literal=20now=0A+only=20return=20that=20string;=20= it=20is=20not=20used=20as=20a=20docstring.=20=20Example:=0A+=0A+=20=20=20= =20(defun=20sing-a-song=20()=0A+=20=20=20=20=20=20"Sing=20a=20song.")=0A= +=0A+The=20above=20function=20returns=20the=20string=20'"Sing=20a=20= song."'=20but=20has=20no=0A+docstring.=20=20Previously,=20that=20string=20= was=20used=20as=20both=20a=20docstring=20and=0A+return=20value,=20which=20= was=20never=20what=20the=20programmer=20wanted.=20=20If=20you=20want=0A= +the=20string=20to=20be=20a=20docstring,=20add=20an=20explicit=20return=20= value.=0A+=0A+This=20change=20applies=20to=20'defun',=20'defsubst',=20= 'defmacro'=20and=20'lambda'=0A+forms;=20other=20defining=20forms=20such=20= as=20'cl-defun'=20already=20worked=20this=20way.=0A+=0A=20**=20New=20or=20= changed=20byte-compilation=20warnings=0A=20=0A=20---=0Adiff=20--git=20= a/lisp/emacs-lisp/bytecomp.el=20b/lisp/emacs-lisp/bytecomp.el=0Aindex=20= c3355eedd75..cf0e6d600dd=20100644=0A---=20a/lisp/emacs-lisp/bytecomp.el=0A= +++=20b/lisp/emacs-lisp/bytecomp.el=0A@@=20-3061,12=20+3061,11=20@@=20= byte-compile-lambda=0A=20=09=20=20(append=20(if=20(not=20= lexical-binding)=20arglistvars)=0A=20=20=20=20=20=20=20=20=20=20=20=20=20= =20=20=20=20=20=20byte-compile-bound-variables))=0A=20=09=20(body=20(cdr=20= (cdr=20fun)))=0A-=09=20(doc=20(if=20(stringp=20(car=20body))=0A+=20=20=20= =20=20=20=20=20=20;;=20Treat=20a=20final=20string=20literal=20as=20a=20= value,=20not=20a=20doc=20string.=0A+=09=20(doc=20(if=20(and=20(cdr=20= body)=20(stringp=20(car=20body)))=0A=20=20=20=20=20=20=20=20=20=20=20=20=20= =20=20=20=20=20=20(prog1=20(car=20body)=0A-=20=20=20=20=20=20=20=20=20=20= =20=20=20=20=20=20=20=20=20=20;;=20Discard=20the=20doc=20string=20from=20= the=20body=0A-=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20= ;;=20unless=20it=20is=20the=20last=20element=20of=20the=20body.=0A-=20=20= =20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20(if=20(cdr=20body)=0A= -=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20= (setq=20body=20(cdr=20body))))))=0A+=20=20=20=20=20=20=20=20=20=20=20=20=20= =20=20=20=20=20=20=20;;=20Discard=20the=20doc=20string=20from=20the=20= body.=0A+=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20= (setq=20body=20(cdr=20body)))))=0A=20=09=20(int=20(assq=20'interactive=20= body))=0A=20=20=20=20=20=20=20=20=20=20command-modes)=0A=20=20=20=20=20= (when=20lexical-binding=0Adiff=20--git=20= a/test/lisp/emacs-lisp/bytecomp-resources/warn-wide-docstring-defun.el=20= b/test/lisp/emacs-lisp/bytecomp-resources/warn-wide-docstring-defun.el=0A= index=2094b0e80c979..571f7f6f095=20100644=0A---=20= a/test/lisp/emacs-lisp/bytecomp-resources/warn-wide-docstring-defun.el=0A= +++=20= b/test/lisp/emacs-lisp/bytecomp-resources/warn-wide-docstring-defun.el=0A= @@=20-1,3=20+1,4=20@@=0A=20;;;=20-*-=20lexical-binding:=20t=20-*-=0A=20= (defun=20foo=20()=0A-=20=20= "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx= xxxxxxxxxxxxxxxxxxxxxxxxxxx")=0A+=20=20= "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx= xxxxxxxxxxxxxxxxxxxxxxxxxxx"=0A+=20=20nil)=0A--=20=0A2.32.0=20(Apple=20= Git-132)=0A=0A= --Apple-Mail=_D7AB377B-44E6-48B3-B7C6-B3B28CA95FFE--