Document buffer-swap-text+save-excursion interaction

* doc/lispref/buffers.texi (Swapping Text):
* src/buffer.c (Fbuffer_swap_text): Add warning about interaction of
`buffer-swap-text' and `save-excursion' (Bug #4655).

1 files changed, 6 insertions, 0 deletions

diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi
index 1f7f263fb21..740d7cfd8a1 100644
--- a/doc/lispref/buffers.texi
+++ b/doc/lispref/buffers.texi
@@ -1211,6 +1211,12 @@ swapped as well: the positions of point and mark, all the markers, the
 overlays, the text properties, the undo list, the value of the
 @code{enable-multibyte-characters} flag (@pxref{Text Representations,
 enable-multibyte-characters}), etc.
+
+@strong{Warning:} If this function is called from within a
+@code{save-excursion} form, the current buffer will be set to
+@var{buffer} upon leaving the form, since the marker used by
+@code{save-excursion} to save the position and buffer will be swapped
+as well.
 @end defun
 
   If you use @code{buffer-swap-text} on a file-visiting buffer, you