From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Stefan Monnier Newsgroups: gmane.emacs.devel Subject: Re: [elpa] externals/vertico-posframe 39dbdfe 6/7: Fix checkdoc warn. Date: Fri, 29 Oct 2021 09:42:14 -0400 Message-ID: References: <20211029015739.26727.26392@vcs0.savannah.gnu.org> <20211029015754.E319220983@vcs0.savannah.gnu.org> <831r44s5s4.fsf@gnu.org> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="16330"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/28.0.50 (gnu/linux) Cc: emacs-devel@gnu.org, tumashu@163.com To: Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Fri Oct 29 15:43:24 2021 Return-path: Envelope-to: ged-emacs-devel@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 1mgSAG-000412-Hx for ged-emacs-devel@m.gmane-mx.org; Fri, 29 Oct 2021 15:43:24 +0200 Original-Received: from localhost ([::1]:60880 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mgSAF-0002hM-D4 for ged-emacs-devel@m.gmane-mx.org; Fri, 29 Oct 2021 09:43:23 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:33088) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mgS9N-00021R-BH for emacs-devel@gnu.org; Fri, 29 Oct 2021 09:42:29 -0400 Original-Received: from mailscanner.iro.umontreal.ca ([132.204.25.50]:8231) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mgS9J-0004YR-Kl; Fri, 29 Oct 2021 09:42:27 -0400 Original-Received: from pmg2.iro.umontreal.ca (localhost.localdomain [127.0.0.1]) by pmg2.iro.umontreal.ca (Proxmox) with ESMTP id 2B31A80043; Fri, 29 Oct 2021 09:42:23 -0400 (EDT) Original-Received: from mail01.iro.umontreal.ca (unknown [172.31.2.1]) by pmg2.iro.umontreal.ca (Proxmox) with ESMTP id 5A28280608; Fri, 29 Oct 2021 09:42:21 -0400 (EDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=iro.umontreal.ca; s=mail; t=1635514941; bh=kquciB1YtKaaE4flqf+m+EG87rArhquUjqQCodtjQnk=; h=From:To:Cc:Subject:References:Date:In-Reply-To:From; b=IgFpoyRT3pCYv53PdYHuaUxi0BUveNIKuAE4DGopHqV7kAdkUqClkbPlr/e7cF/XV 2I2eYlon1ekn56KX72QOYQ8rqsKYt0n1huAra5bucZ1QYy4fuA83dK6zMIkm7a6aH5 joXw4FLeAvbO+3/LBgYT9I+Thr3pdSMFxF5ncOaQZl4uDPFV4LyGY389qy7C3CIxLy QHTLMp8nonXwtW7RUSu+6ly6LhKyzJyHTANO4EEXy0/+/+pnC0Nn1JRNWUICcoZKyj 3WUW93amqqHInE6+alF+2OYbj/oI5Rb+WwuurdVPVfaQKKXM/SCJEZlFPrOyob4DMO OwJAVh7nYr7uQ== Original-Received: from pastel (unknown [45.72.241.23]) by mail01.iro.umontreal.ca (Postfix) with ESMTPSA id 2E215120867; Fri, 29 Oct 2021 09:42:21 -0400 (EDT) In-Reply-To: <831r44s5s4.fsf@gnu.org> (Eli Zaretskii's message of "Fri, 29 Oct 2021 09:29:15 +0300") Received-SPF: pass client-ip=132.204.25.50; envelope-from=monnier@iro.umontreal.ca; helo=mailscanner.iro.umontreal.ca X-Spam_score_int: -42 X-Spam_score: -4.3 X-Spam_bar: ---- X-Spam_report: (-4.3 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, RCVD_IN_DNSWL_MED=-2.3, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.io gmane.emacs.devel:278192 Archived-At: Eli Zaretskii [2021-10-29 09:29:15] wrote: >> In my experience checkdoc's warning about arguments not mentioned in the >> docstring aren't very helpful (it's quite common that the arguments >> aren't mentioned. Here for example, it's the same args as those of >> `minibuffer-message`, so there's no strong need to repeat the doc here. >> Also the function could come without docstring in which case >> checkdoc wouldn't complain about that missing arg doc). >>=20 >> Maybe we should change checkdoc not to request args be mentioned? >> Or at least not for non-interactive functions? > > I'm not sure such a change will be for the better. To be honest, I'm not sure either. I do find most that the warning about args not mentioned in the docstring to be by far the one that creates the largest number of "false positives" (in most cases, they're actually not false in he sense that indeed the args aren't mentioned, but their lack is not a serious problem). IME, this warning corresponds to a WIBNI rather than a FIXME. It's the main reason why I never try to reach "0 warnings" from checkdoc. > Many times people don't reference the arguments there because they are > unaware of our style conventions, or because they cannot find the > wording which would mention the arguments and still stay within the > 80-char limitation. Hmm... AFAIK this warning is unrelated to the first line or the 80 columns conventions. It just says things like: Argument =E2=80=98prompt=E2=80=99 should appear (as PROMPT) in the doc = string > (I understand that none of the above is the case for code that you, > Stefan, write, but you are one of the few exceptions in this regard.) I know I'm perfect, but actually I do find this (usually annoying) warning occasionally useful, to prod me into completing a doc string. > I'd like to remind people why we have this convention: it's because > some Help commands, such as apropos, only display the first line of > the doc string. So it's important for that line to be as informant as > possible. I think you're talking about a different convention than the one I'm talking about (and the patch I quoted fixes the one I'm talking about but doesn't touche the first line of the docstring). Stefan