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

[Eli Zaretskii]

> +(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.  The above doc string,
by contrast, is not user-level enough:

  . The first sentence says "move forward down", which is confusing
    and unclear.

  . 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.

  . 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.

The way we usually write doc strings for commands is to describe the
interactive behavior first in terms clear to users.  Then we describe
how the function should be called from Lisp and how it behaves.  And
finally we describe which other functions and variables affect the
behavior, including any technical details of interest to Lisp
programmers.  I hope this doc string (and the rest of the
documentation for these features) could be rewritten along these
lines.

(I would have tried rewriting them myself, but I don't see any
*-ts-mode modes which take advantage of these new features, so I
couldn't try them to confirm my guesses and expectations from the
behavior, and make sure what I write will be accurate.  So I'm asking
the people who know how this should behave to please improve the
documentation instead.)

TIA