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

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

> I have now done that.
 
> Fixed.
 
> Done.
 
> Fixed.

Great.  Thank you for all of those changes, sight unseen.

> > 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.
> >
> The previous paragraph of the doc string describes the interactive
> behavior:
> 
>   When called interactively, if variable `browse-url-new-window-flag' is
>   non-nil, load the document in a new window, if possible, otherwise use
>   a random existing one.  A non-nil interactive prefix argument reverses
>   the effect of `browse-url-new-window-flag'.
> 
> So this part was already okay (in other functions as well).

Sorry; I do not understand.  The doc string speaks about behavior
for when it is called interactively and when it is called
non-interactively.

I fail to see how it is called interactively, since it is not a
command - it has no `interactive' spec.  Are you perhaps counting
something like `M-: (browse-url-default-browser...)' as an
interactive call?  Normally that is not what the doc means by
"interactive".

Am I missing something?  The doc string still seems wacko, to me.
I admit that I have not studied all of the code in browse-url.el,
but I shouldn't have to, just to grasp what a doc string is saying.

This doc string talks about situations where the function is
called interactively, which I do not see as a possibility.

And it refers to an "optional second argument NEW-WINDOW", but
the lambda list is (URL &rest ARGS), and the doc string in no
way introduces NEW WINDOW in terms of those parameters.
Sure, users can figure out that NEW-WINDOW, if present, must be
the first element of list ARGS.  But it would be a lot clearer
if the doc string just talked about an optional second argument,
and said directly what its effect is.

I don't want to belabor this any more that we have already.  If
you really think this doc string is clear now, great.  It's not
so important that it be clear to me.  Thanks for having taken a
second look at it and having made the changes you made.