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

[Eli Zaretskii <eliz@gnu.org>]

> Date: Fri, 25 Dec 2015 15:07:06 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>
> 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?