From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.bugs Subject: bug#19421: 25.0.50; doc string of `browse-url' must describe parameter ARGS Date: Sat, 26 Dec 2015 11:11:51 +0200 Message-ID: <83bn9dk208.fsf@gnu.org> References: <87mvsywduo.fsf@gnus.org> <8db0a3c8-08b4-40c3-93a8-23ec9fcd8174@default> Reply-To: Eli Zaretskii NNTP-Posting-Host: plane.gmane.org X-Trace: ger.gmane.org 1451121148 29104 80.91.229.3 (26 Dec 2015 09:12:28 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sat, 26 Dec 2015 09:12:28 +0000 (UTC) Cc: larsi@gnus.org, 19421@debbugs.gnu.org To: Drew Adams Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sat Dec 26 10:12:16 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 1aCktb-0002LF-Lf for geb-bug-gnu-emacs@m.gmane.org; Sat, 26 Dec 2015 10:12:15 +0100 Original-Received: from localhost ([::1]:37958 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aCktV-00016b-RI for geb-bug-gnu-emacs@m.gmane.org; Sat, 26 Dec 2015 04:12:09 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:53835) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aCktR-00016U-VG for bug-gnu-emacs@gnu.org; Sat, 26 Dec 2015 04:12:07 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1aCktO-0005xv-PS for bug-gnu-emacs@gnu.org; Sat, 26 Dec 2015 04:12:05 -0500 Original-Received: from debbugs.gnu.org ([208.118.235.43]:57368) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aCktO-0005xo-LZ for bug-gnu-emacs@gnu.org; Sat, 26 Dec 2015 04:12:02 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84) (envelope-from ) id 1aCktO-0001C0-Fg for bug-gnu-emacs@gnu.org; Sat, 26 Dec 2015 04:12: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: Sat, 26 Dec 2015 09:12:02 +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.14511210764528 (code B ref 19421); Sat, 26 Dec 2015 09:12:02 +0000 Original-Received: (at 19421) by debbugs.gnu.org; 26 Dec 2015 09:11:16 +0000 Original-Received: from localhost ([127.0.0.1]:36737 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84) (envelope-from ) id 1aCkse-0001Ay-KG for submit@debbugs.gnu.org; Sat, 26 Dec 2015 04:11:16 -0500 Original-Received: from eggs.gnu.org ([208.118.235.92]:34528) by debbugs.gnu.org with esmtp (Exim 4.84) (envelope-from ) id 1aCksd-0001Al-4b for 19421@debbugs.gnu.org; Sat, 26 Dec 2015 04:11:15 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1aCksU-0005t1-GZ for 19421@debbugs.gnu.org; Sat, 26 Dec 2015 04:11:09 -0500 Original-Received: from fencepost.gnu.org ([2001:4830:134:3::e]:45132) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aCksU-0005sx-Cg; Sat, 26 Dec 2015 04:11:06 -0500 Original-Received: from 84.94.185.246.cable.012.net.il ([84.94.185.246]:1046 helo=HOME-C4E4A596F7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_128_CBC_SHA1:128) (Exim 4.82) (envelope-from ) id 1aCksT-0005Fh-Lk; Sat, 26 Dec 2015 04:11:06 -0500 In-reply-to: <8db0a3c8-08b4-40c3-93a8-23ec9fcd8174@default> (message from Drew Adams on Fri, 25 Dec 2015 15:07:06 -0800 (PST)) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] 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:110586 Archived-At: > Date: Fri, 25 Dec 2015 15:07:06 -0800 (PST) > From: Drew Adams > Cc: 19421@debbugs.gnu.org > > > > 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. > > > > 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'. What would you like us to say about ARGS? If you looked at the functions that can be invoked by browse-url, you know that they either ignore ARGS or (in a few cases) use ARGS to pass the NEW-WINDOW flag, in which case the corresponding function documents that. So this ARGS thingy is really for custom-written browser functions, in which case whoever writes them should know what ARGS are for, and should document that in the doc string of the function she writes. > 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? Do you want us to say that ARGS are ignored? Is that what would in your opinion fix this bug? > As for `browse-url-default-browser', its doc string does not > even have the lame excuse you used: > > > The doc string says "Passes any ARGS to the browser function." > > It says nothing at all about ARGS. Because it is just a dispatcher -- it invokes other functions, which mostly ignore ARGS altogether. > 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. I don't think URL should need any explanations in a package that deals with browsing URLs. So this part is a red herring, IMO. > 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. You should watch your language if you want your comments to be taken seriously. If every minor issue is "a mess" and "a shame", then what words can you use for real problems?