; Assorted documentation fixes in recent changes

* etc/NEWS: Minor copyedits of recent entries.

* src/keyboard.c (Finternal_handle_focus_in):
* lisp/frame.el (frame-focus-state): Doc fixes.

* doc/lispref/hooks.texi (Standard Hooks): Mention
after-delete-frame-functions.

4 files changed, 24 insertions, 22 deletions

diff --git a/doc/lispref/hooks.texi b/doc/lispref/hooks.texi
index e374d02defb..0d50a293f26 100644
--- a/doc/lispref/hooks.texi
+++ b/doc/lispref/hooks.texi
@@ -124,6 +124,7 @@ The command loop runs this soon after @code{post-command-hook} (q.v.).
 @xref{Input Focus}.
 
 @item delete-frame-functions
+@itemx after-delete-frame-functions
 @xref{Deleting Frames}.
 
 @item delete-terminal-functions
diff --git a/etc/NEWS b/etc/NEWS
index 52cedc4d401..50433eb7f28 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -590,26 +590,26 @@ manual for more details.
 * Lisp Changes in Emacs 27.1
 
 +++
-** New hook `after-delete-frame-functions'.  Works like
-   `delete-frame-functions', but runs after the frame to be deleted
-   has been made dead and removed from the frame list, simplifying
-   some kinds of code.
+** New hook 'after-delete-frame-functions'.
+This works like 'delete-frame-functions', but runs after the frame to
+be deleted has been made dead and removed from the frame list.
 
 +++
-** New focus state inspection interface: `focus-in-hook' and
-   `focus-out-hook' are marked obsolete.  Instead, attach to
-   `after-focus-change-function' using `add-function' and inspect the
-   focus state of each frame using `frame-focus-state'.
+** New frame focus state inspection interface.
+The hooks 'focus-in-hook' and 'focus-out-hook' are now obsolete.
+Instead, attach to 'after-focus-change-function' using 'add-function'
+and inspect the focus state of each frame using 'frame-focus-state'.
 
 +++
-** Emacs now requests and recognizes focus-change notifications from
-   terminals that support the feature, meaning that `focus-in-hook'
-   and `focus-out-hook' may run for TTY frames.
+** Emacs now requests and recognizes focus-change notifications from TTYs.
+On terminal emulators that support the feature, Emacs can now support
+'focus-in-hook' and 'focus-out-hook' for TTY frames.
 
 +++
-** Face specifications (of the kind used in `face-remapping-alist')
-   now support filters, allowing faces to vary between windows display
-   the same buffer.
+** Window-specific face remapping.
+Face specifications (of the kind used in 'face-remapping-alist')
+now support filters, allowing faces to vary between different windows
+displaying the same buffer.
 
 +++
 ** New function assoc-delete-all.
@@ -634,7 +634,7 @@ backslash.  For example:
 ** Omitting variables after '&optional' and '&rest' is now allowed.
 For example (defun foo (&optional)) is no longer an error.  This is
 sometimes convenient when writing macros.  See the ChangeLog entry
-titled "Allow `&rest' or `&optional' without following variable
+titled "Allow '&rest' or '&optional' without following variable
 (Bug#29165)" for a full listing of which arglists are accepted across
 versions.
 
diff --git a/lisp/frame.el b/lisp/frame.el
index 38f785901e7..7dbd346bd91 100644
--- a/lisp/frame.el
+++ b/lisp/frame.el
@@ -131,9 +131,10 @@ appended when the minibuffer frame is created."
 
 (defun frame-focus-state (&optional frame)
   "Return FRAME's last known focus state.
+If nil or omitted, FRAME defaults to the selected frame.
+
 Return nil if the frame is definitely known not be focused, t if
-the frame is known to be focused, and 'unknown if we don't know.  If
-FRAME is nil, query the selected frame."
+the frame is known to be focused, and `unknown' if we don't know."
   (let* ((frame (or frame (selected-frame)))
          (tty-top-frame (tty-top-frame frame)))
     (if (not tty-top-frame)
diff --git a/src/keyboard.c b/src/keyboard.c
index 0d6a6ad56b8..12fc33787a3 100644
--- a/src/keyboard.c
+++ b/src/keyboard.c
@@ -6605,8 +6605,8 @@ has the same base event type and all the specified modifiers.  */)
 
 DEFUN ("internal-handle-focus-in", Finternal_handle_focus_in,
        Sinternal_handle_focus_in, 1, 1, 0,
-       doc: /* Internally handle focus-in events, possibly generating
-an artifical switch-frame event.  */)
+       doc: /* Internally handle focus-in events.
+This function potentially generates an artifical switch-frame event.  */)
      (Lisp_Object event)
 {
   Lisp_Object frame;
@@ -6616,9 +6616,9 @@ an artifical switch-frame event.  */)
     error ("invalid focus-in event");
 
   /* Conceptually, the concept of window manager focus on a particular
-   frame and the Emacs selected frame shouldn't be related, but for a
-   long time, we automatically switched the selected frame in response
-   to focus events, so let's keep doing that.  */
+     frame and the Emacs selected frame shouldn't be related, but for
+     a long time, we automatically switched the selected frame in
+     response to focus events, so let's keep doing that.  */
   bool switching = (!EQ (frame, internal_last_event_frame)
                     && !EQ (frame, selected_frame));
   internal_last_event_frame = frame;