Re: master 5a8a5e3d: Input fontification for M-x shell

[Eli Zaretskii <eliz@gnu.org>]

> From: <miha@kamnitnik.top>
> Cc: Lars Ingebrigtsen <larsi@gnus.org>, emacs-devel@gnu.org
> Date: Sat, 10 Sep 2022 17:53:51 +0200
> 
> > It is not useful to have customizable user options whose doc string
> > doesn't explain their purpose.  It makes discovery and use of such
> > options much harder.  Imagine a user who upgrades to Emacs 29 and runs
> > "M-x customize-changed" to learn about new options in the new version:
> > what will such user understand by reading the doc string of this
> > option?  There's no explanation what are indirect shell fontification
> > buffers, nor how and for what purpose they are used.  Without that, it
> > is impossible to understand when and how this hook could be useful.
> >
> > Could you please augment the doc string with the above in mind?
> >
> > The same goes for several other hooks in your changes installed today.
> 
> Thanks. Will something like this be good? I also tried to address your
> other e-mail.

It is much better, thanks.

>  (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.
> +If input fontification or indentation is enabled, create an
> +indirect buffer and set up its major mode and syntax

You say "create an indirect buffer and set up...", but isn't that done
by some of the other code you submitted?  If so, instead of
"create...and set up...", which implies that the user of this variable
must do so, the doc string should say something like

  If input fontification or indentation is enabled, function
  `so-and-so' creates an indirect buffer and sets up its major mode
  and syntax highlighting.  This hook is useful for running in that
  indirect buffer when its major mode is turned on.

> -(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 set-up 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."

Ah, now this makes sense.  Thanks.