Re: master 3c50edb2b50 2/3: Add new variable 'down-list-function' for 'treesit-down-list'

[Juri Linkov]

>> +(defun treesit-down-list (&optional arg)
>> +  "Move forward down one level of parentheses.
>> +What constitutes a level of parentheses is determined by
>> +`sexp-list' in `treesit-thing-settings' that usually defines
>> +parentheses-like expressions.
>> +
>> +This command is the tree-sitter variant of `down-list'
>> +redefined by the variable `down-list-function'.
>> +
>> +ARG is described in the docstring of `down-list'."
>
> This doc string (and other pieces of user-level documentation
> installed recently that deal with sexp and list movement based on
> tree-sitter) need to be improved.
>
> Let me try to explain what I find missing in the installed
> documentation, using the above as example.
>
> The above is a command, not just a function.  Doc strings of commands
> should be user-facing: they should describe the interactive behavior
> clearly and in terms understandable by users.

It doesn't need to be a command.  The interactive spec was copied
from 'treesit-forward-sexp' where it was added by Theodor maybe for
the rare case when someone might want to use it as a command.
If this is not suitable, then removing the interactive spec is fine.

> The above doc string, by contrast, is not user-level enough:
>
>   . The first sentence says "move forward down", which is confusing
>     and unclear.

This sentence was copied from the existing docstring of 'down-list'.

>   . The doc string doesn't say what constitutes a level of
>     parentheses; instead, it sends the user to look that up in
>     treesit-thing-settings.  My guess is that in most cases such a
>     level is either literal parenthetical expression or brace- or
>     bracket-delimited one; if that is true, just saying that it is in
>     most cases so will go a long way towards explaining the behavior.

The term "parentheses-like expressions" was copied from 'down-list'
whose authors probably thought it's self-explanatory.

>   . It doesn't explain the effect of the prefix argument, something
>     that every command should do.  Sending the user to look that up in
>     another command is only justified if the effect of the argument is
>     very complex to describe.

This is not a command intended for users.  If the interactive spec
is a problem, it can be removed.  Is this what you would prefer?