master 37b2c2fcdd9: ; Improve the documentation of a recent commit

[Eli Zaretskii]

branch: master
commit 37b2c2fcdd9344f33f843d3fd5f9129babdf172f
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    ; Improve the documentation of a recent commit
    
    * etc/NEWS:
    * doc/lispref/frames.texi (Deleting Frames): Improve documentation
    of 'frame-deletable-p'.
---
 doc/lispref/frames.texi | 7 +++++--
 etc/NEWS                | 7 ++++---
 2 files changed, 9 insertions(+), 5 deletions(-)

diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi
index 197f4c17b46..73e6b6268d4 100644
--- a/doc/lispref/frames.texi
+++ b/doc/lispref/frames.texi
@@ -2839,8 +2839,11 @@ than deleted.
 @end deffn
 
 The following function checks whether a frame can be safely deleted.  It
-is useful to avoid that a subsequent call of @code{delete-frame} throws
-an error.
+is useful for avoiding the situation whereby a subsequent call of
+@code{delete-frame} fails to delete its argument @var{frame} and/or
+signals an error.  To that end, your Lisp program should call
+@code{delete-frame} only if the following function returns
+non-@code{nil}.
 
 @defun frame-deletable-p &optional frame
 This function returns non-@code{nil} if the frame specified by
diff --git a/etc/NEWS b/etc/NEWS
index 0593f07d381..56a45068daf 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -315,9 +315,10 @@ helps to restore window buffers across Emacs sessions.
 
 +++
 *** New function 'frame-deletable-p'.
-Calling this function before 'delete-frame' is useful to avoid how the
-latter function signals an error when its FRAME argument cannot be
-deleted.
+If this function returns nil, the following call to 'delete-frame' might
+fail to delete its argument FRAME or might signal an error.  It is
+therefore advisable to use this function as part of a condition that
+determines whether to call 'delete-frame'.
 
 +++
 *** New value 'force' for user option 'frame-inhibit-implied-resize'.