[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#19421: 25.0.50; doc string of `browse-url' must describe parameter A
From: |
Eli Zaretskii |
Subject: |
bug#19421: 25.0.50; doc string of `browse-url' must describe parameter ARGS |
Date: |
Sat, 26 Dec 2015 20:53:39 +0200 |
> Date: Sat, 26 Dec 2015 08:40:36 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: larsi@gnus.org, 19421@debbugs.gnu.org
>
> > 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.
I have now done that.
> 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).
Fixed.
> > > 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.
Done.
> 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?
Fixed.
> 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.
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).