Package: emacs;
Reported by: Drew Adams <drew.adams <at> oracle.com>
Date: Sat, 20 Dec 2014 23:08:02 UTC
Severity: minor
Found in version 25.0.50
Done: Lars Ingebrigtsen <larsi <at> gnus.org>
Bug is archived. No further changes may be made.
Message #22 received at 19421 <at> debbugs.gnu.org (full text, mbox):
From: Drew Adams <drew.adams <at> oracle.com> To: Eli Zaretskii <eliz <at> gnu.org>, Drew Adams <drew.adams <at> oracle.com> Cc: larsi <at> gnus.org, 19421 <at> debbugs.gnu.org Subject: RE: bug#19421: 25.0.50; doc string of `browse-url' must describe parameter ARGS Date: Sat, 26 Dec 2015 08:40:36 -0800 (PST)
> What would you like us to say about ARGS? Say what it is for? Name and describe its structure or its parts, if any of them (NEW-WINDOW?) are significant? I don't know the functions, so I can't really say what might be appropriate to say about ARGS, here. > 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. If a given function that has an ARGS &rest parameter does nothing else with ARGS except pass it on to some other function, it is enough for the doc of the first function to say that - as usual. Certainly the function's doc should say nothing about "NEW-WINDOW" unless either NEW-WINDOW is in the parameter list or the doc describes it in terms of parameters that are in the list (e.g., as one of the members of argument-list ARGS). The mention of NEW-WINDOW comes out of the blue and is incomprehensible to a user reading the doc string (this user, at least). > 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. I have no complaints about imaginary doc strings of possible user-written functions. The bug report is about doc strings of predefined Emacs functions that have ARGS as &rest parameter. > > 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? I don't know the behavior, so I won't pretend to prescribe what the doc should say. IF the ARGS are always completely ignored by a function that accepts &rest ARGS as arguments, then that is not a doc problem - the function should not accept arguments if it in fact always ignores them. But if it passes the ARGS on to some other function (for example) then that's what the doc string should say. That is not ignoring the arguments. And in that case it need say nothing more than that: "ARGS are passed to function ____" or "ARGS are passed to the function that is the value of variable ____" or similar. This is the usual treatment, no? I don't think I'm inventing anything, here. > > 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. Then that's what its doc should say: it passes ARGS to other functions (and name or otherwise specify what those functions are or can be). And whether or not those other functions ignore ARGS is irrelevant to _this_ doc string for _this_ function. > > 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. It need not say that parameter URL is a url, granted. But it might want to say something about it being a string, or about it being passed to ____, or something else - I don't know. If you think there is nothing at all to say about URL, I'm OK with that. Frankly, I'm comfortable with you, Eli, just taking a look at the bug report. I'm not very happy with it having been summarily closed without any consideration. I'm not really keen to jump back in on this and argue about it - I really don't care that much. I would hope that someone would either take a considered look at it and DTRT or that it would simply remain open until someone does that. That's the proper respect to show to bug reports and to the users who took the time to report them - even when the reports might be mistaken or foolish. Users who report bugs are trying to improve Emacs. They are not trying to make life miserable for the volunteers who maintain Emacs and who are also, like the users who report bugs, trying to improve Emacs. If you don't have the time to consider a report carefully, then please leave it open for now. Closing bug reports summarily, just to get the numbers down (?), is the kind of misguided thing seen sometimes in non-free software circles. Back to the report... You dropped this: > And yet something about an "optional second argument > NEW-WINDOW", which is not even present in the lambda list. What about that? No doc bug? And this: > Worse yet: It says "When called non-interactively", > suggesting that the function could be called interactively. > But it cannot - it is not a command. No acknowledgment that I might have a point and there are indeed some problems with this doc string, there at least. Instead, a sermon that if I want help then I should not say that this doc string is a "mess" and it is a "shame" to summarily close such bugs instead of at least acknowledging them or (better) making a minimal attempt to improve the doc. It's perfectly understandable that such a bug is not regarded as high-priority. But if you recognize it as a bug then why close it? And if you do _not_ recognize that a doc string that talks about NEW-WINDOW and calls the function a command, when NEW-WINDOW is undefined wrt the parameter list and the function is not interactive, then I disagree - it is a bug. However insignificant one might think such a doc bug is, at least one user (and I hardly use browse-url) thinks it is important enough to report. Whether you want to spend time looking into it or fixing it is another question - I make no argument that this bug is very important. But why close it, if it is a bug? You have not heard me complaining that this bug has not been fixed. My complaint is about it being closed summarily. That's all.
GNU bug tracking system
Copyright (C) 1999 Darren O. Benham,
1997,2003 nCipher Corporation Ltd,
1994-97 Ian Jackson.