Improve some shell highlight doc strings

* lisp/shell.el (shell-highlight-undef-mode-restart): Rename function.
* lisp/shell.el (shell-comint-fl-enable):
(shell--highlight-undef-indirect)
* lisp/ielm.el (ielm-comint-fl-enable):
* lisp/comint.el: (comint--fl-fontify-region): Improve doc strings.

3 files changed, 38 insertions, 16 deletions

diff --git a/lisp/comint.el b/lisp/comint.el
index 751e561d3e3..696dac3d12b 100644
--- a/lisp/comint.el
+++ b/lisp/comint.el
@@ -4030,9 +4030,13 @@ to calling this function and `change-major-mode-hook' along with
 `after-change-major-mode-hook' are bound to nil.")
 
 (defcustom comint-indirect-setup-hook nil
-  "Hook run after setting up an indirect comint fontification buffer.
-It is run after the indirect buffer is set up for fontification
-of input regions."
+  "Hook run in an indirect buffer for input fontification.
+Input fontification and indentation, if enabled, is performed in
+an indirect buffer, whose major mode and syntax highlighting are
+set up according to `comint-indirect-setup-function'.  After this
+setup is done, run this hook with the indirect buffer as the
+current buffer.  This can be used to further customize
+fontification and other behaviour of the indirect buffer."
   :group 'comint
   :type 'hook
   :version "29.1")
@@ -4117,8 +4121,8 @@ setting."
 
 (defun comint--fl-fontify-region (fun beg end verbose)
   "Fontify process output and user input in the current comint buffer.
-First, highlight the region between BEG and END using FUN.  Then
-highlight only the input text in the region with the help of an
+First, fontify the region between BEG and END using FUN.  Then
+fontify only the input text in the region with the help of an
 indirect buffer.  VERBOSE is passed to the fontify-region
 functions.  Skip fontification of input regions with non-nil
 `comint--fl-inhibit-fontification' text property."
diff --git a/lisp/ielm.el b/lisp/ielm.el
index 211804210c3..4a10c002976 100644
--- a/lisp/ielm.el
+++ b/lisp/ielm.el
@@ -475,16 +475,23 @@ nonempty, then flushes the buffer."
 ;;; Input fontification
 
 (defcustom ielm-comint-fl-enable t
-  "Enable highlighting of input in ielm buffers.
+  "Enable fontification of input in ielm buffers.
 This variable only has effect when creating an ielm buffer.  Use
-the command `comint-fl-mode' to toggle highlighting of input in
+the command `comint-fl-mode' to toggle fontification of input in
 an already existing ielm buffer."
   :type 'boolean
   :safe 'booleanp
   :version "29.1")
 
 (defcustom ielm-indirect-setup-hook nil
-  "Hook run after setting up an indirect ielm fontification buffer."
+  "Hook run in an indirect buffer for input fontification.
+Input fontification and indentation of an IELM buffer, if
+enabled, is performed in an indirect buffer, whose indentation
+and syntax highlighting are set up with `emacs-lisp-mode'.  In
+addition to `comint-indirect-setup-hook', run this hook with the
+indirect buffer as the current buffer after its setup is done.
+This can be used to further customize fontification and other
+behaviour of the indirect buffer."
   :type 'boolean
   :safe 'booleanp
   :version "29.1")
diff --git a/lisp/shell.el b/lisp/shell.el
index eccac663768..87fd36a5929 100644
--- a/lisp/shell.el
+++ b/lisp/shell.el
@@ -309,16 +309,23 @@ for Shell mode only."
   :group 'shell)
 
 (defcustom shell-comint-fl-enable t
-  "Enable highlighting of input in shell buffers.
+  "Enable fontification of input in shell buffers.
 This variable only has effect when the shell is started.  Use the
-command `comint-fl-mode' to toggle highlighting of input."
+command `comint-fl-mode' to toggle fontification of input."
   :type 'boolean
   :group 'shell
   :safe 'booleanp
   :version "29.1")
 
 (defcustom shell-indirect-setup-hook nil
-  "Hook run after setting up an indirect shell fontification buffer."
+  "Hook run in an indirect buffer for input fontification.
+Input fontification and indentation of a `shell-mode' buffer, if
+enabled, is performed in an indirect buffer, whose indentation
+and syntax highlighting is set up with `sh-mode'.  In addition to
+`comint-indirect-setup-hook', run this hook with the indirect
+buffer as the current buffer after its setup is done.  This can
+be used to further customize fontification and other behaviour of
+the indirect buffer."
   :type 'boolean
   :group 'shell
   :safe 'booleanp
@@ -1680,7 +1687,7 @@ Similar to `executable-find', but use cache stored in
     t))
 
 (defvar-local shell--highlight-undef-indirect nil
-  "t if shell commands are fontified in `comint-indirect-buffer'.")
+  "Non-nil if shell commands are fontified in `comint-indirect-buffer'.")
 
 (declare-function sh-feature "sh-script" (alist &optional function))
 (defvar sh-leading-keywords)
@@ -1700,7 +1707,7 @@ works better if `comint-fl-mode' is enabled."
             (font-lock-remove-keywords nil shell-highlight-undef-keywords))))
     (font-lock-remove-keywords nil shell-highlight-undef-keywords))
   (remove-hook 'comint-fl-mode-hook
-               #'shell-highlight-undef-reset-mode t)
+               #'shell-highlight-undef-mode-restart t)
 
   (when shell-highlight-undef-mode
     (when comint-use-prompt-regexp
@@ -1742,12 +1749,16 @@ works better if `comint-fl-mode' is enabled."
             (t (funcall setup))))
 
     (add-hook 'comint-fl-mode-hook
-              #'shell-highlight-undef-reset-mode nil t))
+              #'shell-highlight-undef-mode-restart nil t))
 
   (font-lock-flush))
 
-(defun shell-highlight-undef-reset-mode ()
-  "If `shell-highlight-undef-mode' is on, turn it off and on."
+(defun shell-highlight-undef-mode-restart ()
+  "If `shell-highlight-undef-mode' is on, restart it.
+`shell-highlight-undef-mode' performs its setup differently
+depending on `comint-fl-mode'.  It's useful to call this function
+when switching `comint-fl-mode' in order to make
+`shell-highlight-undef-mode' redo its setup."
   (when shell-highlight-undef-mode
     (shell-highlight-undef-mode 1)))