Subject: Re: bug#59662: 29.0.50; [PATCH] Add treesit--indent-defun

From: Eli Zaretskii <[email-masked]>
Date: Fri, 09 Dec 2022 22:20:05 +0200

> From: Theodor Thornhill <[email-masked]>
> Cc: [email-masked], [email-masked], [email-masked],
>  [email-masked]
> Date: Fri, 09 Dec 2022 16:50:25 +0100
> 
> diff --git a/doc/emacs/programs.texi b/doc/emacs/programs.texi
> index ba8475e86a..cc06a003e2 100644
> --- a/doc/emacs/programs.texi
> +++ b/doc/emacs/programs.texi
> @@ -409,6 +409,14 @@ Multi-line Indent
>  @table @kbd
>  @item C-M-q
>  Reindent all the lines within one parenthetical grouping.
> +@item M-q
> +Major modes that derive from @code{prog-mode} can reindent all the
> +lines within a defun around point using
> +@code{prog-mode-fill-reindent-defun}.  The bounds of of a defun is
> +decided by @code{beginning-of-defun-function} and
> +@code{end-of-defun-function}.  If point is inside a comment or a
> +doc-string, refill that paragraph instead, using
> +@code{fill-paragraph-function}.

The 2 variables you mention should have @vindex entries.  Also, please
add a cross-reference to the mode in elisp manual where these two
variables are described.

> +*** New command 'prog-fill-reindent-defun'
> +This command either fills a single paragraph in a defun, such as a
> +doc-string, or a comment.  If point is inside normal code, it
> +(re)indents the surrounding defun.

These two sentences should be one sentence, otherwise that 'either" is
out of place.  Something like

  This command either fills a single paragraph in a defun, such as a
  doc-string, or a comment, or (re)indents the surrounding defun if
  point is not in a comment or a string.

>                                        Bound by default in
> +'prog-mode-map' to 'M-q'.

"It is by default bound to 'M-q' in 'prog-mode' and all its
descendants."

> +(defun prog-fill-reindent-defun (&optional argument)
> +  "Refill paragraph or reindent the definition that the point is on.
> +
> +If the point is in a string, or in a comment, or there is a
> +comment on the current line, fill the paragraph that the point is
> +in or is on the same line.

I don't understand the difference between "point is in a string, or in
a comment" and "there is a comment on the current line".  

> +Otherwise, reindent the definition around or below point."

Likewise this one is confusing.