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

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

[Drew Adams]

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''

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

[Eli Zaretskii]

tags 24312 + wontfix
thanks

> Date: Fri, 26 Aug 2016 09:37:15 -0700 (PDT)
> From: Drew Adams <drew.adams@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.

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

[Drew Adams]

> > 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

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

[Noam Postavsky]

On Fri, Aug 26, 2016 at 12:37 PM, Drew Adams <drew.adams@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

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

[Eli Zaretskii]

> From: Noam Postavsky <npostavs@users.sourceforge.net>
> Date: Fri, 26 Aug 2016 14:51:09 -0400
> Cc: 24312@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.

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

[Drew Adams]

> >  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.

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

[npostavs]

tags 24312 - wontfix
fixed 24312 25.1
quit

Drew Adams <drew.adams@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".