bug#4605: Description of `buffer-swap-text' is vague and inadequate.

[Alan Mackenzie]

Hi, Stefan, Hi, Emacs!

The Elisp manual page "Swapping Text", says that `buffer-swap-text'
"swaps text between the current buffer and its argument BUFFER."

This tells me nothing.  I'd have to read the source (or maybe try it
out) to find out what this function does.

What does "swap" mean here?  How much text is "swapped".  What does
"between" mean?

A naive guess would suggest this command takes a bit of text out of
buffer A and dumps it into buffer B, simultaneously moving a bit of B
into A.

There is also no entry in .../src/ChangeLog (or ChangeLog.10, ...)
marking the introduction of this command.

-- 
Alan Mackenzie (Nuremberg, Germany).