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

Previous Next

Full log

View this message in rfc822 format

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: larsi <at> gnus.org, 19421 <at> debbugs.gnu.org
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 <at> oracle.com>
> Cc: larsi <at> gnus.org, 19421 <at> 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).

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.