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

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

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

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: 

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