GNU bug report logs - #24312
25.1.50; doc string of `tags-query-replace' - wrong signature

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 24312 in the body.
You can then email your comments to 24312 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 25.1.50; doc string of `tags-query-replace' - wrong signature
Date: Fri, 26 Aug 2016 09:37:15 -0700 (PDT)

The doc string refers to parameters that are not in the calling sequence
(signature).

The signature is wrong.  It says this:

(tags-query-replace FROM TO &optional DELIMITED FILE-LIST-FORM)

But it should say this:

(tags-query-replace FROM TO &optional DELIMITED FILE-LIST-FORM
                                      START END)

The doc string says this (correctly):

 Fifth and sixth arguments START and END are accepted, for compatibility
 with ‘query-replace-regexp’, and ignored.

The doc cannot reference optional args START and END unless they are in
the signature.  It does not matter, for this, that they are ignored by
the function body.

The signature should be corrected as noted above.  The doc is OK.


In GNU Emacs 25.1.50.1 (i686-pc-mingw32)
 of 2015-12-10
Repository revision: 6148555ee5a3d0139ae517803718b3e0357933c7
Windowing system distributor 'Microsoft Corp.', version 6.1.7601
Configured using:
 'configure --prefix=/c/Devel/emacs/snapshot/trunk --enable-checking=yes
 --enable-check-lisp-object-type --without-compress-install 'CFLAGS=-Og
 -ggdb3' LDFLAGS=-Lc:/Devel/emacs/lib 'CPPFLAGS=-DGC_MCHECK=1
 -Ic:/Devel/emacs/include''

Message #12 received at 24312-done <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 24312-done <at> debbugs.gnu.org
Subject: Re: bug#24312: 25.1.50;
 doc string of `tags-query-replace' - wrong signature
Date: Fri, 26 Aug 2016 20:35:52 +0300

tags 24312 + wontfix
thanks

> Date: Fri, 26 Aug 2016 09:37:15 -0700 (PDT)
> From: Drew Adams <drew.adams <at> oracle.com>
> 
> The doc string refers to parameters that are not in the calling sequence
> (signature).
> 
> The signature is wrong.  It says this:
> 
> (tags-query-replace FROM TO &optional DELIMITED FILE-LIST-FORM)
> 
> But it should say this:
> 
> (tags-query-replace FROM TO &optional DELIMITED FILE-LIST-FORM
>                                       START END)
> 
> The doc string says this (correctly):
> 
>  Fifth and sixth arguments START and END are accepted, for compatibility
>  with ‘query-replace-regexp’, and ignored.

So it's obviously deliberate.

> The doc cannot reference optional args START and END unless they are in
> the signature.

They are optional, so yes, the doc can do that.

Closing.

Message #15 received at 24312-done <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 24312-done <at> debbugs.gnu.org
Subject: RE: bug#24312: 25.1.50; doc string of `tags-query-replace' - wrong
 signature
Date: Fri, 26 Aug 2016 11:16:23 -0700 (PDT)

> > The doc string says this (correctly):
> >
> >  Fifth and sixth arguments START and END are accepted, for compatibility
> >  with ‘query-replace-regexp’, and ignored.
> 
> So it's obviously deliberate.
> 
> > The doc cannot reference optional args START and END unless they are in
> > the signature.
> 
> They are optional, so yes, the doc can do that.
> 
> Closing.

Suit yourself.

FYI, searching the doc strings of all functions defined in my session
for "ignored", I find NONE that show a signature without an optional
argument that is mentioned as being ignored.  ZERO.

On the other hand, I find all of these functions whose doc strings
state that an optional argument is ignored and that show the ignored
argument in the signature:

after-find-file
cvs-quikdir
dframe-set-timer
dired-revert
gnus-agent-regenerate
gnus-delay-initialize
iso-german
iso-gtex2iso
iso-iso2duden
iso-iso2gtex
iso-iso2sgml
iso-iso2tex
iso-sgml2iso
iso-spanish
iso-tex2iso
pcomplete-opt
url-copy-file
view-buffer-other-frame
view-buffer-other-window
widget-image-insert

Message #18 received at 24312 <at> debbugs.gnu.org (full text, mbox):

From: Noam Postavsky <npostavs <at> users.sourceforge.net>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 24312 <at> debbugs.gnu.org
Subject: Re: bug#24312: 25.1.50;
 doc string of `tags-query-replace' - wrong signature
Date: Fri, 26 Aug 2016 14:51:09 -0400

On Fri, Aug 26, 2016 at 12:37 PM, Drew Adams <drew.adams <at> oracle.com> wrote:
>
> The doc string says this (correctly):
>
>  Fifth and sixth arguments START and END are accepted, for compatibility
>  with ‘query-replace-regexp’, and ignored.

AFAICT, the doc is wrong, because the arguments are not
accepted/ignored. Did I miss something?

(let ((from 1)
      (to 2)
      (delimited 3)
      (file-list-form 4)
      (start 5)
      (end 6))
  (tags-query-replace from to delimited file-list-form start end)) ;=>
Wrong number of arguments: (2 . 4), 6

Message #21 received at 24312 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Noam Postavsky <npostavs <at> users.sourceforge.net>
Cc: drew.adams <at> oracle.com, 24312 <at> debbugs.gnu.org
Subject: Re: bug#24312: 25.1.50;
 doc string of `tags-query-replace' - wrong signature
Date: Fri, 26 Aug 2016 22:15:30 +0300

> From: Noam Postavsky <npostavs <at> users.sourceforge.net>
> Date: Fri, 26 Aug 2016 14:51:09 -0400
> Cc: 24312 <at> debbugs.gnu.org
> 
>   (tags-query-replace from to delimited file-list-form start end)) ;=>
> Wrong number of arguments: (2 . 4), 6

Please fix it then, and thanks.

Message #24 received at 24312 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Noam Postavsky <npostavs <at> users.sourceforge.net>
Cc: 24312 <at> debbugs.gnu.org
Subject: RE: bug#24312: 25.1.50; doc string of `tags-query-replace' - wrong
 signature
Date: Fri, 26 Aug 2016 12:52:47 -0700 (PDT)

> >  Fifth and sixth arguments START and END are accepted, for compatibility
> >  with ‘query-replace-regexp’, and ignored.
> 
> AFAICT, the doc is wrong, because the arguments are not
> accepted/ignored. Did I miss something?
> 
> (let ((from 1)(to 2)(delimited 3)(file-list-form 4)(start 5)(end 6))
>   (tags-query-replace from to delimited file-list-form start end)) ;=>
> Wrong number of arguments: (2 . 4), 6

Good catch.  So presumably, assuming that the code behaves as intended,
that sentence should just be removed from the doc.

Message #27 received at 24312 <at> debbugs.gnu.org (full text, mbox):

From: npostavs <at> users.sourceforge.net
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 24312 <at> debbugs.gnu.org
Subject: Re: bug#24312: 25.1.50;
 doc string of `tags-query-replace' - wrong signature
Date: Fri, 26 Aug 2016 22:38:13 -0400

tags 24312 - wontfix
fixed 24312 25.1
quit

Drew Adams <drew.adams <at> oracle.com> writes:

>> >  Fifth and sixth arguments START and END are accepted, for compatibility
>> >  with ‘query-replace-regexp’, and ignored.
>> 
>> AFAICT, the doc is wrong, because the arguments are not
>> accepted/ignored. Did I miss something?
>> 
>> (let ((from 1)(to 2)(delimited 3)(file-list-form 4)(start 5)(end 6))
>>   (tags-query-replace from to delimited file-list-form start end)) ;=>
>> Wrong number of arguments: (2 . 4), 6
>
> Good catch.  So presumably, assuming that the code behaves as intended,
> that sentence should just be removed from the doc.

Done in 17197d0a "Fix tags-query-replace docstring".

Previous Next

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