emacs-31 924d88a736e: ; Warn about killed buffers returned by 'window-prev-buffers' (Bug#81370)

branch: emacs-31
commit 924d88a736eea3dca19d04af1960e560a45182eb
Author: Martin Rudalics <[email protected]>
Commit: Martin Rudalics <[email protected]>

    ; Warn about killed buffers returned by 'window-prev-buffers' (Bug#81370)
    
    * src/window.c (Fwindow_prev_buffers): In doc-string mention
    that the return value may reference killed buffers.
    * doc/lispref/windows.texi (Window History): Mention that the
    return value of 'window-prev-buffers' may reference buffers that
    have been killed.
---
 doc/lispref/windows.texi | 5 +++++
 src/window.c             | 6 +++++-
 2 files changed, 10 insertions(+), 1 deletion(-)

diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index 16b82a6a29e..9caaa5e6901 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -4939,6 +4939,11 @@ and @var{window-pos} is a marker that gives the window point position
 The list is ordered so that earlier elements correspond to more
 recently-shown buffers, and the first element usually corresponds to the
 buffer most recently removed from the window.
+
+As a rule, elements are removed from this list when their buffer gets
+killed.  In rare cases, however, elements may have survived the killing
+of their buffer.  It's a good idea therefore to always check buffers for
+liveness when processing the return value of this function.
 @end defun
 
 @defun set-window-prev-buffers window prev-buffers
diff --git a/src/window.c b/src/window.c
index 792c43d0555..0373af7ef27 100644
--- a/src/window.c
+++ b/src/window.c
@@ -2326,7 +2326,11 @@ WINDOW must be a live window and defaults to the selected one.
 
 The return value is a list of elements (BUFFER WINDOW-START POS),
 where BUFFER is a buffer, WINDOW-START is the start position of the
-window for that buffer, and POS is a window-specific point value.  */)
+window for that buffer, and POS is a window-specific point value.
+
+In rare ocasions BUFFER may have been already killed.  It's therefore
+advisable to always check the return value for the occurrence of dead
+buffers before using it.  */)
   (Lisp_Object window)
 {
   return decode_live_window (window)->prev_buffers;