From debbugs-submit-bounces@debbugs.gnu.org Wed Nov 15 18:49:57 2023 Received: (at submit) by debbugs.gnu.org; 15 Nov 2023 23:49:57 +0000 Received: from localhost ([127.0.0.1]:54177 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1r3Pdt-0005WE-7z for submit@debbugs.gnu.org; Wed, 15 Nov 2023 18:49:57 -0500 Received: from lists.gnu.org ([2001:470:142::17]:60034) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1r3Pdo-0005Vq-F8 for submit@debbugs.gnu.org; Wed, 15 Nov 2023 18:49:56 -0500 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 1r3Pdg-0003xP-UR for bug-gnu-emacs@gnu.org; Wed, 15 Nov 2023 18:49:44 -0500 Received: from out-179.mta1.migadu.com ([95.215.58.179]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1r3Pde-0001Bw-2K for bug-gnu-emacs@gnu.org; Wed, 15 Nov 2023 18:49:44 -0500 X-Report-Abuse: Please report any abuse attempt to abuse@migadu.com and include these headers. DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=jeremybryant.net; s=key1; t=1700092179; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type; bh=xAX+09BOm+q8dp18NhUFFqa4DJ99oZdCLB2KNgSs2Vg=; b=TEH68bEphhe4807Um/EQveimIDAO7Cq2N+EEnqhWQI08hJmzmlOAmjv1Qizcqfw6JirGIk /IeufSR0gpf5v34G44anQHqj1BgqiGRZxfkNRAymePN5A2iYGeGcQ+0s0OZEi2dNHJ8EJd gYSLGQT+GqXerYzy7oX2qEU2TsU9Gw4GWK5gDrKyt2whsfyq4+0JmuEkUyv5WqExdF7sPC Zg6czu8f4F/yyS3iEUIuzsgyevAeZpF9nUSItU8978v237t8l+GVdXxtfK2aS8qGa/lMyF w8aoJJW2Bi606h3fxK1lveEZ8cqt2SToPgEIk6dJ+3SAAXiMtfc8k6SOw4JEZQ== From: Jeremy Bryant To: bug-gnu-emacs@gnu.org Subject: [PATCH] Improve docstring argument conventions Date: Wed, 15 Nov 2023 23:47:35 +0000 Message-ID: <874jhmvapa.fsf@jeremybryant.net> MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" X-Migadu-Flow: FLOW_OUT Received-SPF: pass client-ip=95.215.58.179; envelope-from=jb@jeremybryant.net; helo=out-179.mta1.migadu.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 autolearn=ham autolearn_force=no X-Spam_action: no action X-Spam-Score: 0.9 (/) X-Debbugs-Envelope-To: submit X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -0.1 (/) --=-=-= Content-Type: text/plain Tags: patch Eli, following this convention mentioned in a recent bug, > The first sentence of a doc string should preferably mention the > mandatory arguments (TYPE and ARG). If the result is too long to fit > on a single line, consider saying only the main part there, and then > describing the details in the following lines. It doesn't appear to me to be in the manual. So I'm submitting a patch to amend the manual. This is my first patch to the manual so let me know if this contribution is in the right section, or needs changing before installing. --=-=-= Content-Type: text/patch Content-Disposition: attachment; filename=0001-Improve-docstring-argument-conventions.patch >From e6aa69b0195e413a6c93edbb931f08db2892dc47 Mon Sep 17 00:00:00 2001 From: Jeremy Bryant Date: Wed, 15 Nov 2023 23:44:06 +0000 Subject: [PATCH] Improve docstring argument conventions * doc/lispref/tips.texi (Documentation Tips): Improve docstring argument procedence conventions --- doc/lispref/tips.texi | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi index f760b2554f0..9f1c15525cb 100644 --- a/doc/lispref/tips.texi +++ b/doc/lispref/tips.texi @@ -642,7 +642,8 @@ Documentation Tips in a function call. If the function has many arguments, then it is not feasible to mention them all in the first line; in that case, the first line should mention the first few arguments, including the most -important arguments. +important arguments. Mandatory arguments should be documented before +optional arguments. @item When a function's documentation string mentions the value of an argument -- 2.40.1 --=-=-=-- From debbugs-submit-bounces@debbugs.gnu.org Thu Nov 16 01:15:22 2023 Received: (at 67217) by debbugs.gnu.org; 16 Nov 2023 06:15:22 +0000 Received: from localhost ([127.0.0.1]:54339 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1r3Ver-00080f-QM for submit@debbugs.gnu.org; Thu, 16 Nov 2023 01:15:22 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:50194) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1r3Veq-00080O-7H for 67217@debbugs.gnu.org; Thu, 16 Nov 2023 01:15:20 -0500 Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1r3Vek-0003wb-Na; Thu, 16 Nov 2023 01:15:14 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=MIME-version:References:Subject:In-Reply-To:To:From: Date; bh=DeXb7BCwjnVGri43rZRzLeQ57v/AyG2oFfoI3kEGRqY=; b=r2oEx092gVEC870Xqius fVvVy3EohncSAQxLrqRVYWVIp2EPUi6uSCk5HjlaPYEKF6p3gEGDNFjZbkSdWPWrKdeX56DD+NoGz 5kz2ktCkh0oWI8CYBB4TGV2yXQ55xi2Lk7fBJt+ytP6vAld4McZxiuUM/yKTJWUscUI6ofODRvkjd 90htbhvCKBrQbHdW5OIFaCR1FY21GQ8P86TGhvDv3TGcfARQZ/GCbfp2R7Y4ZkZ0dvzY1R3MdNXNp iTesz2gIC+S6XG82wo1ZTPxuQW2xCjxUi9dH3xsT7spAqInWCB9AZFuG6vj46KApJT7D6jumJFiiK xAOuiA1zvOzR6w==; Date: Thu, 16 Nov 2023 08:15:03 +0200 Message-Id: <83y1eyp6l4.fsf@gnu.org> From: Eli Zaretskii To: Jeremy Bryant In-Reply-To: <874jhmvapa.fsf@jeremybryant.net> (bug-gnu-emacs@gnu.org) Subject: Re: bug#67217: [PATCH] Improve docstring argument conventions References: <874jhmvapa.fsf@jeremybryant.net> MIME-version: 1.0 Content-type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 67217 Cc: 67217@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > Date: Wed, 15 Nov 2023 23:47:35 +0000 > From: Jeremy Bryant via "Bug reports for GNU Emacs, > the Swiss army knife of text editors" > > Eli, following this convention mentioned in a recent bug, > > > The first sentence of a doc string should preferably mention the > > mandatory arguments (TYPE and ARG). If the result is too long to fit > > on a single line, consider saying only the main part there, and then > > describing the details in the following lines. > > It doesn't appear to me to be in the manual. Yes, it does: • The first line should mention all the important arguments of the function, and should mention them in the order that they are written in a function call. If the function has many arguments, then it is not feasible to mention them all in the first line; in that case, the first line should mention the first few arguments, including the most important arguments. > diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi > index f760b2554f0..9f1c15525cb 100644 > --- a/doc/lispref/tips.texi > +++ b/doc/lispref/tips.texi > @@ -642,7 +642,8 @@ Documentation Tips > in a function call. If the function has many arguments, then it is > not feasible to mention them all in the first line; in that case, the > first line should mention the first few arguments, including the most > -important arguments. > +important arguments. Mandatory arguments should be documented before > +optional arguments. What you suggest to add is already there: it says to mention the arguments in the order they are written in the signature, which means mandatory first, then the optional ones (if they are important enough). What I said was the usual interpretation of "most important", nothing more, nothing less. My intent was that the optional variables don't need to be mentioned if that is somehow unneeded or impractical or something else, but the mandatory ones should generally be mentioned. The manual says the same using a different wording. So let me turn the table and ask you: why did you think the existing text is insufficient in this aspect? From debbugs-submit-bounces@debbugs.gnu.org Thu Nov 16 18:57:18 2023 Received: (at 67217) by debbugs.gnu.org; 16 Nov 2023 23:57:19 +0000 Received: from localhost ([127.0.0.1]:44872 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1r3mEY-0005Qc-Fm for submit@debbugs.gnu.org; Thu, 16 Nov 2023 18:57:18 -0500 Received: from out-173.mta1.migadu.com ([2001:41d0:203:375::ad]:54570) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1r3mEV-0005QQ-Rp for 67217@debbugs.gnu.org; Thu, 16 Nov 2023 18:57:17 -0500 References: <874jhmvapa.fsf@jeremybryant.net> <83y1eyp6l4.fsf@gnu.org> DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=jeremybryant.net; s=key1; t=1700179033; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=Xda939QXz8dwIn0lTgqobs46SzbEd2A0hZbDGvF6HHI=; b=OzpVbqQWXlTDzwgJ8mrNTqNVN9hXfIzI8q9QEfXAgg8Ns5aYheOd6R7ENFzqyy9Ka7HzMh Q/opEU2XMp3T5rrY8oXTdtSvLvpMtIor2VEB3ythnaWTh1/6U/7wsAKVzIEdzmcNlPRvmm LSxLWWhIajGYp3m4sAVoV3b4qV96JZ3IQ1cWcO9ftluOLPvF4rN5S8A5WQXB7gdr+aumLu vAOoNFKL4fmksycrYnAAHHTML9HOCkPCvO9kH5dtBxdC9dzdmILmfm+5GpzLbq6HvfOBgb HNmaYDTtB/BIokUhiBWjxnid9k3HQsj6jEIA78QmCgMUbSnmRj7TcwXtX9jioA== X-Report-Abuse: Please report any abuse attempt to abuse@migadu.com and include these headers. From: Jeremy Bryant To: Eli Zaretskii Subject: Re: bug#67217: [PATCH] Improve docstring argument conventions Date: Thu, 16 Nov 2023 23:55:29 +0000 In-reply-to: <83y1eyp6l4.fsf@gnu.org> Message-ID: <87v8a1tfoo.fsf@jeremybryant.net> MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Migadu-Flow: FLOW_OUT X-Spam-Score: -0.0 (/) X-Debbugs-Envelope-To: 67217 Cc: 67217@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.0 (-) Eli Zaretskii writes: >> Date: Wed, 15 Nov 2023 23:47:35 +0000 >> From: Jeremy Bryant via "Bug reports for GNU Emacs, >> the Swiss army knife of text editors" >>=20 >> Eli, following this convention mentioned in a recent bug, >>=20 >> > The first sentence of a doc string should preferably mention the >> > mandatory arguments (TYPE and ARG). If the result is too long to fit >> > on a single line, consider saying only the main part there, and then >> > describing the details in the following lines. >>=20 >> It doesn't appear to me to be in the manual. > > Yes, it does: > > =E2=80=A2 The first line should mention all the important arguments of= the > function, and should mention them in the order that they are > written in a function call. If the function has many arguments, > then it is not feasible to mention them all in the first line; in > that case, the first line should mention the first few arguments, > including the most important arguments. > >> diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi >> index f760b2554f0..9f1c15525cb 100644 >> --- a/doc/lispref/tips.texi >> +++ b/doc/lispref/tips.texi >> @@ -642,7 +642,8 @@ Documentation Tips >> in a function call. If the function has many arguments, then it is >> not feasible to mention them all in the first line; in that case, the >> first line should mention the first few arguments, including the most >> -important arguments. >> +important arguments. Mandatory arguments should be documented before >> +optional arguments. > > What you suggest to add is already there: it says to mention the > arguments in the order they are written in the signature, which means > mandatory first, then the optional ones (if they are important > enough). > > What I said was the usual interpretation of "most important", nothing > more, nothing less. My intent was that the optional variables don't > need to be mentioned if that is somehow unneeded or impractical or > something else, but the mandatory ones should generally be mentioned. > The manual says the same using a different wording. > > So let me turn the table and ask you: why did you think the existing > text is insufficient in this aspect? I thought your wording was clearer than the manual and proposed adapting the manual to your wording and to be more explicit about mandatory and opti= onal. I accept that it is comparable. From debbugs-submit-bounces@debbugs.gnu.org Fri Nov 17 02:06:32 2023 Received: (at 67217-done) by debbugs.gnu.org; 17 Nov 2023 07:06:32 +0000 Received: from localhost ([127.0.0.1]:45000 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1r3svw-0000yl-Fb for submit@debbugs.gnu.org; Fri, 17 Nov 2023 02:06:32 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:44656) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1r3svu-0000yT-2R for 67217-done@debbugs.gnu.org; Fri, 17 Nov 2023 02:06:31 -0500 Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1r3svo-0003Ji-FN; Fri, 17 Nov 2023 02:06:24 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=References:Subject:In-Reply-To:To:From:Date: mime-version; bh=WlZAqtuqQiOmreoSVqOVnOzt44AOoY8J9DGkBVEZFhs=; b=epJYzybcxr8F CmwPd0DIDwYRO5SyrvkUgyv4jYSUMWlNGurupJ1ZWdpKTjpqYv25q3Cp7ZLM74jzKzBKhZzn2xDsD oypsv9CiGQuw2wJirW7OMpXWmd3xM4r14+E9NEZZZ9EeadiP+6dG0w2+jpAaVKpuJHur7e/SVPrLp zhxVekISHDxlAnqJS2QCh4TDl1iPbYWQnnFR88m7n8Pcv9VICqK2onQj7IrXPD6YFi4EBqRata+lX th6BE8x6+h3veVOoPFXe0T5uLau8yzz5psRowtfF/2trzgMovKJMiXjGpQH3mzL56vtm5jOm6JZgm GPnrxxeMId1M58qbnTGvsg==; Date: Fri, 17 Nov 2023 09:06:16 +0200 Message-Id: <83a5rcq2on.fsf@gnu.org> From: Eli Zaretskii To: Jeremy Bryant In-Reply-To: <87v8a1tfoo.fsf@jeremybryant.net> (message from Jeremy Bryant on Thu, 16 Nov 2023 23:55:29 +0000) Subject: Re: bug#67217: [PATCH] Improve docstring argument conventions References: <874jhmvapa.fsf@jeremybryant.net> <83y1eyp6l4.fsf@gnu.org> <87v8a1tfoo.fsf@jeremybryant.net> X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 67217-done Cc: 67217-done@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > From: Jeremy Bryant > Cc: 67217@debbugs.gnu.org > Date: Thu, 16 Nov 2023 23:55:29 +0000 > > > Eli Zaretskii writes: > > > So let me turn the table and ask you: why did you think the existing > > text is insufficient in this aspect? > > I thought your wording was clearer than the manual and proposed adapting > the manual to your wording and to be more explicit about mandatory and optional. > > I accept that it is comparable. "Mandatory" is just my personal rule of thumb, which is just easy to explain. But maybe you are right, and it helps explain this tip, thanks for pointing that out. So I've now added a note about mandatory arguments there, in the hope that it helps. And with that, I'm closing the bug. From unknown Tue Jun 17 22:27:15 2025 Received: (at fakecontrol) by fakecontrolmessage; To: internal_control@debbugs.gnu.org From: Debbugs Internal Request Subject: Internal Control Message-Id: bug archived. Date: Fri, 15 Dec 2023 12:24:05 +0000 User-Agent: Fakemail v42.6.9 # This is a fake control message. # # The action: # bug archived. thanks # This fakemail brought to you by your local debbugs # administrator