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#43307: 28.0.50; `diff-no-select': no documentation for BUF argument Date: Fri, 11 Sep 2020 09:07:54 +0300 Message-ID: <834ko4j16t.fsf@gnu.org> References: <87r1r94a41.fsf@gnus.org> Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="39610"; mail-complaints-to="usenet@ciao.gmane.io" Cc: p.stephani2@gmail.com, 43307@debbugs.gnu.org To: Lars Ingebrigtsen Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Fri Sep 11 08:08:10 2020 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 1kGcEE-000ADo-3Y for geb-bug-gnu-emacs@m.gmane-mx.org; Fri, 11 Sep 2020 08:08:10 +0200 Original-Received: from localhost ([::1]:54510 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kGcED-0007qR-5s for geb-bug-gnu-emacs@m.gmane-mx.org; Fri, 11 Sep 2020 02:08:09 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:59822) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kGcE6-0007oc-Eg for bug-gnu-emacs@gnu.org; Fri, 11 Sep 2020 02:08:02 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:58799) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1kGcE6-00089g-5k for bug-gnu-emacs@gnu.org; Fri, 11 Sep 2020 02:08:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1kGcE5-00074I-Uh for bug-gnu-emacs@gnu.org; Fri, 11 Sep 2020 02:08:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Fri, 11 Sep 2020 06:08:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 43307 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: fixed Original-Received: via spool by 43307-submit@debbugs.gnu.org id=B43307.159980447727160 (code B ref 43307); Fri, 11 Sep 2020 06:08:01 +0000 Original-Received: (at 43307) by debbugs.gnu.org; 11 Sep 2020 06:07:57 +0000 Original-Received: from localhost ([127.0.0.1]:42112 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kGcE0-000740-ON for submit@debbugs.gnu.org; Fri, 11 Sep 2020 02:07:56 -0400 Original-Received: from eggs.gnu.org ([209.51.188.92]:55840) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kGcDz-00073n-2e for 43307@debbugs.gnu.org; Fri, 11 Sep 2020 02:07:55 -0400 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]:47689) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kGcDt-00088R-PP; Fri, 11 Sep 2020 02:07:49 -0400 Original-Received: from [176.228.60.248] (port=1634 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1kGcDs-00044w-LT; Fri, 11 Sep 2020 02:07:49 -0400 In-Reply-To: <87r1r94a41.fsf@gnus.org> (message from Lars Ingebrigtsen on Thu, 10 Sep 2020 23:04:14 +0200) 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" Xref: news.gmane.io gmane.emacs.bugs:187792 Archived-At: > From: Lars Ingebrigtsen > Date: Thu, 10 Sep 2020 23:04:14 +0200 > Cc: 43307@debbugs.gnu.org > > Philipp Stephani writes: > > > The signature for `diff-no-select' is: > > > > (diff-no-select OLD NEW &optional SWITCHES NO-ASYNC BUF) > > > > Its docstring refers to `diff' for the meaning of the arguments, but > > `diff' doesn't take an argument, so BUF is undocumented. > > > > Probably `diff-no-select' should also document that the return value is > > BUF if BUF is non-nil. > > I've now amended the doc string of the function on Emacs 28. Thanks, but please backport this to the release branch, as doc changes should be installed there. Also, the new doc string of diff-no-select uses too much of passive tense; can we improve that? And finally, the SWITCHES argument is left semi-documented, since the doc string of 'diff' doesn't tell what happens in non-interactive calls if SWITCHES is specified, and doesn't say what should be its form in that case.