bug#58177: Return value of perform-replace and its documentation string

[Juri Linkov]

>> Thus, I would like to add a feature request to this bug report, namely
>> that the return value of perform-replace, in case it is canceled by
>> the user, be changed from nil to some other value reflecting the
>> replacements considered before the cancel request.
>
> Yes, I think that makes sense.  An alternate value would be to return a
> list of all considered replacements, but marking all the ones after the
> `q' the same way as the `n's are marked.  I.e., `q' as a way of saying
> "skip all the rest", which it is, in a way.
>
> Anybody have any opinions here?

Unfortunately, nil value is used to decide whether to continue
to the next file in multi-buffer replacements.  Examples of such code
including but not limited to: xref--query-replace-1 that contains

(defun xref--query-replace-1 (from to iter)
  (let* ((continue t)
    ...
    (while (and continue ...
      ...
      (setq continue
            (perform-replace from to t t nil nil multi-query-replace-map)))
      ...

and

(defun fileloop-continue ()
    ...
    (while
      ...
      (save-restriction
        (widen)
        (funcall fileloop--operate-function)))
      (setq file-finished t))))

etc.