bug#51940: 29.0.50; [PATCH] Fontification and indentation in M-x shell and ielm

[Eli Zaretskii <eliz@gnu.org>]

> From: <miha@kamnitnik.top>
> Cc: 51940@debbugs.gnu.org
> Date: Thu, 18 Nov 2021 14:32:52 +0100
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> Date: Thu, 18 Nov 2021 10:47:37 +0100
> >> From: miha--- via "Bug reports for GNU Emacs,
> >>  the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>
> >> 
> >> Please find the attached patches which enable fontification and
> >> indentation in M-x shell and ielm. The main fontification and
> >> indentation machinery is implemented in comint.el and should be general
> >> enough for use by other comint derived modes. It works by making an
> >> indirect buffer, putting it in a suitable major mode (sh-mode in
> >> M-x shell buffers, for example) and fontifying and indenting user input
> >> that buffer.
> >
> > Thanks.
> >
> > One general comment about the doc strings:
> >
> >> +(defvar-local comint-indirect-setup-function nil
> >> +  "Function to set up an indirect buffer.
> >
> > here and elsewhere in the changes, please modify the first sentence of
> > the doc strings so that they don't sound too general.  "Set up an
> > indirect buffer" doesn't hint on the fact that this is for comint
> > buffers, not in general about indirect buffers.  The same problem
> > exists with many doc strings in these patches.
> 
> Okay, attached are revised patches with improved doc strings and a fixed
> commit message.

The doc strings are still not specific enough, sorry for being unclear
in what I meant.  Let's take an example:

> +(define-minor-mode comint-fl-mode
> +  "Enable input fontification.

The first line should say something like

  Enable input fontification in comint buffers.

> +(defun comint--fl-off ()
> +  "Disable input fontification for the current buffer."

Similarly here:

  Disable input fontification in the current comint buffer.

> +(defun comint--fl-fontify-region (fun beg end verbose)
> +  "Around advice for `font-lock-fontify-region-function'.

Likewise here: mention comint in the first line.

> +(defcustom shell-highlight-undef-aliases nil
> +  "List of commands to highlight as a command alias."

Here, the doc string should mention shell command aliases, otherwise
it's too general ("command alias" doesn't necessarily imply a shell).

Please go over the doc strings with this criterion in mind, and see
what else needs to be fixed in the same way.

Also, would people who use these modes a lot please try the feature
and provide feedback?

Thanks.