bug#19421: 25.0.50; doc string of `browse-url' must describe parameter ARGS

[Drew Adams <drew.adams@oracle.com>]

> 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.