bug#68824: treesitter support for outline-minor-mode

[Eli Zaretskii <eliz@gnu.org>]

> From: Juri Linkov <juri@linkov.net>
> Cc: casouri@gmail.com,  68824@debbugs.gnu.org
> Date: Thu, 08 Feb 2024 09:40:46 +0200
> 
> > Here is a new patch with a shorter implementation.
> > And I will send a complete patch with documentation changes later.
> 
> So here is a complete patch with documentation changes:

Thanks, some comments below.

> --- a/doc/emacs/text.texi
> +++ b/doc/emacs/text.texi
> @@ -1097,6 +1097,11 @@ Outline Format
>  chapters.  This works as long as no other command starts with
>  @samp{@@chap}.
>  
> +@vindex outline-search-function
> +  Instead of setting the variable @code{outline-regexp}, you can set
> +the variable @code{outline-search-function} to a function that
> +matches the current heading and searches for the next one.

This should tell which arguments will be passed to the function, and
what it is expected to do and return.

> --- a/doc/lispref/parsing.texi
> +++ b/doc/lispref/parsing.texi
> @@ -1895,6 +1895,10 @@ Tree-sitter Major Modes
>  @item
>  If @code{treesit-simple-imenu-settings} (@pxref{Imenu}) is
>  non-@code{nil}, it sets up Imenu.
> +
> +@item
> +If @code{treesit-outline-predicate} is non-@code{nil}, it sets up
> +Outline Minor Mode (@pxref{Outline Minor Mode,,, emacs, The GNU Emacs Manual}).
>  @end itemize

There should be an index entry somewhere, probably right here, for
treesit-outline-predicate.

> --- a/etc/NEWS
> +++ b/etc/NEWS
> @@ -130,6 +130,12 @@ the signature) the automatically inferred function type as well.
>  This user option controls outline visibility in the output buffer of
>  'describe-bindings' when 'describe-bindings-outline' is non-nil.
>  
> +** Outline Mode
> +
> +*** 'outline-minor-mode' is supported in tree-sitter major modes.
> +It can be used in all tree-sitter major modes that set either the
> +variable 'treesit-simple-imenu-settings' or 'treesit-outline-predicate'.

If we don't need any more documentation, this entry should be marked
with "+++".

> +(defvar-local treesit-outline-predicate nil
> +  "Predicate used to find outline headings in the syntax tree.
> +Intended to be set by a major mode.  When nil, the predicate
> +is constructed from the value of `treesit-simple-imenu-settings'
> +when a major mode sets it.")

The doc string should explain with what arguments will the predicate
be called and when it is expected to return non-nil.

> +(defun treesit-outline-predicate-from-imenu (node)
> +  "Return an outline searching predicate created from Imenu.
> +Return the value suitable to set `treesit-outline-predicate'.
> +Create this predicate from the value `treesit-simple-imenu-settings'
> +that major modes set to find Imenu entries.  The assumption here
> +is that the positions of Imenu entries most of the time coincide
> +with the lines of outline headings.  When this assumption fails,
> +you can directly set a proper value to `treesit-outline-predicate'."

Likewise here: please describe in the doc string the signature and
expectations from the predicate returned by this function (or point to
the doc of some other variable/function where that information is
included).

> +(defun treesit-outline-search (&optional bound move backward looking-at)
> +  "Search for the next outline heading in the syntax tree.
> +See the descriptions of arguments in `outline-search-function'."

What about the return value (if it is important)?