Re: Tree-sitter documentation

[Yuan Fu <casouri@gmail.com>]

> On Nov 8, 2022, at 6:40 AM, Eli Zaretskii <eliz@gnu.org> wrote:
> 
>> From: Yuan Fu <casouri@gmail.com>
>> Date: Mon, 7 Nov 2022 12:47:30 -0800
>> Cc: emacs-devel@gnu.org
>> 
>>> In that case, "triplets" is definitely incorrect, but I had no way of
>>> understanding that this is possible.
>>> 
>>> It should be possible top describe this kind of argument list, but
>>> does it really have to be so complicated?  These are not internal
>>> functions, so Lisp programmers will have to battle with this signature
>>> all the time.  Can we make the function's signature easier to
>>> document, understand, and use?
>>> 
>>> For example, what about accepting an alist as the argument, where each
>>> alist element specifies a query and its keyword/value pairs that
>>> customize the query?
>> 
>> Alists has too much layers of parenthesizes that is verbose and easy to get wrong. Compare:
> 
> I don't share your pessimism about alists.  And the way the functions
> are defined now are also very error-prone and complicate the code,
> which needs to distinguish between several very different signatures.

Ah, I’m not saying alist per se has too much layers of parenthesizes, but if we use alists rather than keywords in treesit-font-lock-rules, there really are a lot of parenthesizes. The current signature might be harder to formally explain, but should be pretty intuitive, it’s just a series of queries, and queries can have keyword value pairs preceding it that adds meta information to the query.

I might help to think of treesit-font-lock-rules not as a function but as a macro. 

The code to handle this signature isn’t particularly error-prone, the signal forms you see are just nice type-checks that I added for developer’s aid. They check, for example, that the value of a :language keyword is a symbol, the value of an :override keyword is one of the five possible values, etc. These checks are not related to the signature.

> 
> How about making the query itself the value of a keyword/value pair?
> Like this:
> 
>   :language 'python
>   :override t
>   :feature 'string
>   :query '((string :anchor "\"" @python--treesit-fontify-string)
>            (string) @contextual)

It’s ok, but query isn’t the same as other things. Query is the subject and other keywords adds information to it. I tried to improve the documentation of treesit-font-lock-rules, so hopefully changing the signature is not needed. Is the new version ok to you?

Yuan