[Emacs-diffs] emacs-25 9ba51ed: Document buffer-swap-text+save-excursion interaction

[Noam Postavsky]

branch: emacs-25
commit 9ba51edf62b25c678508a316ec78a09b18d3bf9e
Author: Noam Postavsky <address@hidden>
Commit: Noam Postavsky <address@hidden>

    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).
---
 doc/lispref/buffers.texi |    6 ++++++
 src/buffer.c             |    4 +++-
 2 files changed, 9 insertions(+), 1 deletion(-)

diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi
index 1f7f263..740d7cf 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.
+
address@hidden:} If this function is called from within a
address@hidden form, the current buffer will be set to
address@hidden upon leaving the form, since the marker used by
address@hidden 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
diff --git a/src/buffer.c b/src/buffer.c
index e4269c0..89f4479 100644
--- a/src/buffer.c
+++ b/src/buffer.c
@@ -2231,7 +2231,9 @@ advance_to_char_boundary (ptrdiff_t byte_pos)
 
 DEFUN ("buffer-swap-text", Fbuffer_swap_text, Sbuffer_swap_text,
        1, 1, 0,
-       doc: /* Swap the text between current buffer and BUFFER.  */)
+       doc: /* Swap the text between current buffer and BUFFER.
+Using this function from `save-excursion' might produce surprising
+results, see Info node `(elisp)Swapping Text'.  */)
   (Lisp_Object buffer)
 {
   struct buffer *other_buffer;