docstring of perform-replace

[Roland Winkler]

In GNU Emacs 21.2.1 (i386-pc-linux-gnu, X toolkit, Xaw3d scroll bars)
 of 2002-04-09 on tfkp12
configured using `configure  --prefix=/nfs/common --libexecdir=/nfs/common/lib 
--bindir=/nfs/common/lib/emacs/21.2/bin/i686-Linux 
--mandir=/nfs/common/share/man --infodir=/nfs/common/share/info --with-gcc 
--with-pop --with-x --with-x-toolkit=athena i386-pc-linux'
Important settings:
  value of $LC_ALL: nil
  value of $LC_COLLATE: POSIX
  value of $LC_CTYPE: nil
  value of $LC_MESSAGES: nil
  value of $LC_MONETARY: nil
  value of $LC_NUMERIC: nil
  value of $LC_TIME: nil
  value of $LANG: en_US
  locale-coding-system: iso-latin-1
  default-enable-multibyte-characters: nil

Apperently, the function perform-replace has a well-defined return
value that is used elsewhere. I suggest that this return value
should be documented.

Why is this an issue for me? Today I was bothered by
tags-query-replace. I realized that sometimes tags-query-replace
terminates prematurely when only some part of all files has been
processed. I haven't figured out yet the details when this happens.
All I've figured out is that for a tags-query-replace the while loop
of tags-loop-continue relies on the return value of perform-replace.
If for whatever reason perform-replace returns nil for one file,
tags-loop-continue will not process the other files.

I haven't submitted (yet) a bug report concerning the failure of
tags-query-replace because when I tested everything with GNU Emacs
21.2.50.2 I couldn't reproduce it. So maybe this bug of GNU Emacs
21.2.1 has been fixed already.

But I suggest that the return value of perform-replace should be
documented. It would have helped me a lot to understand what's going
on.

Roland