From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.bugs Subject: bug#67217: [PATCH] Improve docstring argument conventions Date: Thu, 16 Nov 2023 08:15:03 +0200 Message-ID: <83y1eyp6l4.fsf@gnu.org> References: <874jhmvapa.fsf@jeremybryant.net> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="40559"; mail-complaints-to="usenet@ciao.gmane.io" Cc: 67217@debbugs.gnu.org To: Jeremy Bryant Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Thu Nov 16 07:16:20 2023 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 1r3Vfn-000AMr-Jh for geb-bug-gnu-emacs@m.gmane-mx.org; Thu, 16 Nov 2023 07:16:19 +0100 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1r3VfZ-0001F0-Er; Thu, 16 Nov 2023 01:16:05 -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 1r3VfX-0001EY-6I for bug-gnu-emacs@gnu.org; Thu, 16 Nov 2023 01:16:03 -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 1r3VfW-00057d-US for bug-gnu-emacs@gnu.org; Thu, 16 Nov 2023 01:16:02 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1r3VfW-00081e-2O for bug-gnu-emacs@gnu.org; Thu, 16 Nov 2023 01:16:02 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Thu, 16 Nov 2023 06:16:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 67217 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch Original-Received: via spool by 67217-submit@debbugs.gnu.org id=B67217.170011532230800 (code B ref 67217); Thu, 16 Nov 2023 06:16:02 +0000 Original-Received: (at 67217) by debbugs.gnu.org; 16 Nov 2023 06:15:22 +0000 Original-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 Original-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 Original-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==; In-Reply-To: <874jhmvapa.fsf@jeremybryant.net> (bug-gnu-emacs@gnu.org) 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:274436 Archived-At: > 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?