From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Drew Adams Newsgroups: gmane.emacs.bugs Subject: bug#19421: 25.0.50; doc string of `browse-url' must describe parameter ARGS Date: Fri, 25 Dec 2015 15:07:06 -0800 (PST) Message-ID: <8db0a3c8-08b4-40c3-93a8-23ec9fcd8174@default> References: <87mvsywduo.fsf@gnus.org> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable X-Trace: ger.gmane.org 1451084903 11561 80.91.229.3 (25 Dec 2015 23:08:23 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Fri, 25 Dec 2015 23:08:23 +0000 (UTC) Cc: 19421@debbugs.gnu.org To: Lars Ingebrigtsen Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sat Dec 26 00:08:10 2015 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1aCbSz-0001rq-Qt for geb-bug-gnu-emacs@m.gmane.org; Sat, 26 Dec 2015 00:08:09 +0100 Original-Received: from localhost ([::1]:36756 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aCbSz-0006Jr-9n for geb-bug-gnu-emacs@m.gmane.org; Fri, 25 Dec 2015 18:08:09 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:42865) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aCbSv-0006ID-4F for bug-gnu-emacs@gnu.org; Fri, 25 Dec 2015 18:08:06 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1aCbSr-0008Ok-T2 for bug-gnu-emacs@gnu.org; Fri, 25 Dec 2015 18:08:05 -0500 Original-Received: from debbugs.gnu.org ([208.118.235.43]:56583) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aCbSr-0008Og-PI for bug-gnu-emacs@gnu.org; Fri, 25 Dec 2015 18:08:01 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84) (envelope-from ) id 1aCbSr-0004w5-KD for bug-gnu-emacs@gnu.org; Fri, 25 Dec 2015 18:08:01 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Drew Adams Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Fri, 25 Dec 2015 23:08:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 19421 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 19421-submit@debbugs.gnu.org id=B19421.145108483318832 (code B ref 19421); Fri, 25 Dec 2015 23:08:01 +0000 Original-Received: (at 19421) by debbugs.gnu.org; 25 Dec 2015 23:07:13 +0000 Original-Received: from localhost ([127.0.0.1]:35940 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84) (envelope-from ) id 1aCbS5-0004tg-IW for submit@debbugs.gnu.org; Fri, 25 Dec 2015 18:07:13 -0500 Original-Received: from userp1040.oracle.com ([156.151.31.81]:41549) by debbugs.gnu.org with esmtp (Exim 4.84) (envelope-from ) id 1aCbS3-0004tU-Nu for 19421@debbugs.gnu.org; Fri, 25 Dec 2015 18:07:12 -0500 Original-Received: from aserv0022.oracle.com (aserv0022.oracle.com [141.146.126.234]) by userp1040.oracle.com (Sentrion-MTA-4.3.2/Sentrion-MTA-4.3.2) with ESMTP id tBPN741e010587 (version=TLSv1 cipher=DHE-RSA-AES256-SHA bits=256 verify=FAIL); Fri, 25 Dec 2015 23:07:05 GMT Original-Received: from aserv0121.oracle.com (aserv0121.oracle.com [141.146.126.235]) by aserv0022.oracle.com (8.13.8/8.13.8) with ESMTP id tBPN74dB003766 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=FAIL); Fri, 25 Dec 2015 23:07:04 GMT Original-Received: from abhmp0002.oracle.com (abhmp0002.oracle.com [141.146.116.8]) by aserv0121.oracle.com (8.13.8/8.13.8) with ESMTP id tBPN74LA028191; Fri, 25 Dec 2015 23:07:04 GMT In-Reply-To: <87mvsywduo.fsf@gnus.org> X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9 (901082) [OL 12.0.6691.5000 (x86)] X-Source-IP: aserv0022.oracle.com [141.146.126.234] X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 208.118.235.43 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.org@gnu.org Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.bugs:110495 Archived-At: > > Please respect the GNU Emacs convention of > > specifying each of the parameters in the doc string. > > In this case, the doc for ARGS should mention option > > `browse-url-new-window-flag', among other things. >=20 > The doc string says > "Passes any ARGS to the browser function." Yes, and that IS the bug. The doc string does not specify parameter ARGS properly, helpfully, usefully. And there is this part of the same bug report, also ignored: > Same thing for the other functions in browse-url.el that have > an ARGS &rest parameter - e.g., `browse-url-default-browser'. This bug has not been fixed - but you know that. Why not fix it? Why do you not respect the GNU Emacs conventions and its high standards of self-documentation? What possible good reason do you have for not doing the right thing, here? As for `browse-url-default-browser', its doc string does not even have the lame excuse you used:=20 > The doc string says "Passes any ARGS to the browser function." It says nothing at all about ARGS. And it has even more problems. At least in the latest Emacs 25 snapshot I have, which dates from 2015-12-04: * This is the parameters lambda list: (URL &rest ARGS). * This is how the parameters are described in the doc string: "When called non-interactively, optional second argument NEW-WINDOW is used instead of 'browse-url-new-window-flag'." That's it! Nothing about parameter URL. Nothing about &rest-parameter ARGS (the subject of this bug report). And yet something about an "optional second argument NEW-WINDOW", which is not even present in the lambda list. Worse yet: It says "When called non-interactively", suggesting that the function could be called interactively. But it cannot - it is not a command. This is a mess, even if it is a trivial mess to fix. It is a shame to deliberately ignore such a simple, and obvious bug.