feature/tree-sitter 488a6efe32: ; More documentation improvements for treesit

[Eli Zaretskii]

branch: feature/tree-sitter
commit 488a6efe323927a4064afc193b66cd11e2caf77c
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    ; More documentation improvements for treesit
    
    * lisp/treesit.el (treesit-language-at, treesit-range-rules)
    (treesit-font-lock-rules): Doc fixes.
    
    * doc/lispref/parsing.texi (Multiple Languages):
    * doc/lispref/modes.texi (Parser-based Font Lock): Fix wording.
---
 doc/lispref/modes.texi   | 10 +++----
 doc/lispref/parsing.texi | 71 ++++++++++++++++++++++++------------------------
 lisp/treesit.el          | 18 ++++++------
 3 files changed, 50 insertions(+), 49 deletions(-)

diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index 5d9c4b15d8..50dbec35e4 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -3950,15 +3950,15 @@ example:
 @end group
 @end example
 
-This function takes a list of @var{query-spec}s of the form
+This function takes a series of @var{query-spec}s, which are triplets
 @w{@code{@var{:keyword} @var{value} @dots{} @var{query}}}.  Each
 @var{query} is a tree-sitter query in either the string, s-expression
 or compiled form.
 
-Before each query, there are @var{:keyword} @var{value} pairs that
-configure that query.  The @code{:lang} keyword sets the query's
-language.  The @code{:feature} keyword sets the feature name of the
-query.  Users can control which features are enabled with
+The @var{:keyword} and @var{value} pairs configure the query which
+follows them in the argument list.  The @code{:lang} keyword sets the
+query's language.  The @code{:feature} keyword sets the feature name
+of the query.  Users can control which features are enabled with
 @code{font-lock-maximum-decoration} and
 @code{treesit-font-lock-feature-list} (described below).  These two
 keywords are mandated.
diff --git a/doc/lispref/parsing.texi b/doc/lispref/parsing.texi
index 7f7d49b04b..a7a8f8400b 100644
--- a/doc/lispref/parsing.texi
+++ b/doc/lispref/parsing.texi
@@ -1336,7 +1336,8 @@ Lisp programs should call @code{treesit-update-ranges} to 
make sure
 the ranges for each parser are correct before using parsers in a
 buffer, and call @code{treesit-language-at} to figure out the language
 responsible for the text at some position.  Multi-language major modes
-sets @code{treesit-range-settings} and
+set @code{treesit-range-settings} and
+@c FIXME: ``power''?
 @code{treesit-language-at-point-function} respectively to power these
 two functions.  These functions and variables are explained in more
 detail towards the end of the section.
@@ -1417,9 +1418,9 @@ Like other query functions, this function raises the
 @code{treesit-query-error} error if @var{query} is malformed.
 @end defun
 
-@heading Supporting multiple languages as Lisp programs
+@heading Supporting multiple languages in Lisp programs
 
-It should suffice for general Lisp programs to call these two
+It should suffice for general Lisp programs to call the following two
 functions in order to support program sources that mixes multiple
 languages.
 
@@ -1430,8 +1431,8 @@ according to @code{treesit-range-settings}.  If omitted, 
@var{beg}
 defaults to the beginning of the buffer, and @var{end} defaults to the
 end of the buffer.
 
-For example, fontification functions uses this function before
-querying for nodes in a region.
+For example, fontification functions use this function before querying
+for nodes in a region.
 @end defun
 
 @defun treesit-language-at pos
@@ -1444,26 +1445,25 @@ value of @code{treesit-parser-list}.  If there is no 
parser in the
 buffer, it returns @code{nil}.
 @end defun
 
-@heading Supporting multiple languages as major modes
+@heading Supporting multiple languages in major modes
 
 @cindex host language, tree-sitter
-@cindex tree-sitter host language
+@cindex tree-sitter host and embedded languages
 @cindex embedded language, tree-sitter
-@cindex tree-sitter embedded language
 Normally, in a set of languages that can be mixed together, there is a
-host language and one or more embedded languages.  A Lisp program
-usually first parses the whole document with the host language's
-parser, retrieve some information, sets ranges for the embedded
-languages with that information, and then parses the embedded
+@dfn{host language} and one or more @dfn{embedded languages}.  A Lisp
+program usually first parses the whole document with the host
+language's parser, retrieves some information, sets ranges for the
+embedded languages with that information, and then parses the embedded
 languages.
 
 Take a buffer containing @acronym{HTML}, @acronym{CSS} and JavaScript
-as an example.  A lisp program will first parse the whole buffer with
+as an example.  A Lisp program will first parse the whole buffer with
 an @acronym{HTML} parser, then query the parser for
 @code{style_element} and @code{script_element} nodes, which
-corresponds to @acronym{CSS} and JavaScript text, respectively.  Then
+correspond to @acronym{CSS} and JavaScript text, respectively.  Then
 it sets the range of the @acronym{CSS} and JavaScript parser to the
-range in which their corresponding nodes span.
+ranges in which their corresponding nodes span.
 
 Given a simple @acronym{HTML} document:
 
@@ -1476,7 +1476,8 @@ Given a simple @acronym{HTML} document:
 @end group
 @end example
 
-A Lisp program will first parse with a @acronym{HTML} parser, then set
+@noindent
+a Lisp program will first parse with a @acronym{HTML} parser, then set
 ranges for @acronym{CSS} and JavaScript parsers:
 
 @example
@@ -1508,11 +1509,11 @@ ranges for @acronym{CSS} and JavaScript parsers:
 
 Emacs automates this process in @code{treesit-update-ranges}.  A
 multi-language major mode should set @code{treesit-range-settings} so
-that this function knows how to perform this process automatically.
-Major modes should use the helper function @code{treesit-range-rules}
-to generate the value that @code{treesit-range-settings} can have.
-The settings in the following example directly translates to
-operations shown above.
+that @code{treesit-update-ranges} knows how to perform this process
+automatically.  Major modes should use the helper function
+@code{treesit-range-rules} to generate a value that can be assigned to
+@code{treesit-range-settings}.  The settings in the following example
+directly translate into operations shown above.
 
 @example
 @group
@@ -1536,14 +1537,14 @@ takes care of compiling queries and other 
post-processing, and outputs
 a value that @var{treesit-range-settings} can have.
 
 It takes a series of @var{query-spec}s, where each @var{query-spec} is
-of the form @w{@code{@var{:keyword} @var{value} @dots{} @var{query}}}.
-Each @var{query} is a tree-sitter query in either the string,
-s-expression or compiled form, or a function.
+a triplet of arguments @w{@code{@var{:keyword} @var{value} @dots{}
+@var{query}}}.  Each @var{query} is a tree-sitter query in either the
+string, s-expression or compiled form, or a function.
 
-If @var{query} is a tree-sitter qurey, it should be preceded by 2
-pairs of @var{:keyword} and @var{value}, where the @code{:embed}
-keyword specifies the @dfn{embedded language}, and the @code{:host}
-keyword specified the @dfn{host language}.
+If @var{query} is a tree-sitter query, it should be used with the pair
+@var{:keyword} and @var{value}, where the @code{:embed}
+keyword specifies the embedded language, and the @code{:host}
+keyword specified the host language.
 
 @code{treesit-update-ranges} uses @var{query} to figure out how to set
 the ranges for parsers for the embedded language.  It queries
@@ -1551,7 +1552,7 @@ the ranges for parsers for the embedded language.  It 
queries
 the captured nodes span, and applies these ranges to embedded
 language parsers.
 
-If @var{query} is a function, it doesn't need any @var{keyword} and
+If @var{query} is a function, it doesn't need any @var{:keyword} and
 @var{value} pair.  It should be a function that takes 2 arguments,
 @var{start} and @var{end}, and sets the ranges for parsers in the
 current buffer in the region between @var{start} and @var{end}.  It is
@@ -1560,11 +1561,11 @@ encompasses the region between @var{start} and 
@var{end}.
 @end defun
 
 @defvar treesit-range-settings
-This variable helps @code{treesit-update-ranges} to update ranges for
-parsers in the buffer.  It is a list of @var{setting}s where the exact
-format of a @var{setting} is considered internal.  You should use
-@code{treesit-range-rules} to generate a value that this variable can
-have.
+This variable helps @code{treesit-update-ranges} in updating the
+ranges for parsers in the buffer.  It is a list of @var{setting}s
+where the exact format of a @var{setting} is considered internal.  You
+should use @code{treesit-range-rules} to generate a value that this
+variable can have.
 
 @c Because the format is internal, we don't document them here.  Though
 @c we do have it explained in the docstring.  We also expose the fact
@@ -1616,7 +1617,7 @@ This function checks for conditions for activating 
tree-sitter.  It
 checks whether the user turned on tree-sitter for @var{mode}
 (according to @code{treesit-settings}), whether Emacs was built with
 tree-sitter, whether the buffer's size is not too large for
-tree-sitter to handle it, and whether language definition for
+tree-sitter to handle it, and whether the language definition for
 @var{language} is available on the system (@pxref{Language
 Definitions}).
 
diff --git a/lisp/treesit.el b/lisp/treesit.el
index 84be69d8b7..37eee929d7 100644
--- a/lisp/treesit.el
+++ b/lisp/treesit.el
@@ -147,10 +147,10 @@ The function is called with one argument, the position of 
point.")
 
 (defun treesit-language-at (position)
   "Return the language at POSITION.
-Assumes parser ranges are up-to-date.  Returns the return value
-of `treesit-language-at-point-function' if it's non-nil,
-otherwise return the language of the first parser in
-`treesit-parser-list', or nil if there is no parser."
+This function assumes that parser ranges are up-to-date.  It
+returns the return value of `treesit-language-at-point-function'
+if it's non-nil, otherwise it returns the language of the first
+parser in `treesit-parser-list', or nil if there is no parser."
   (if treesit-language-at-point-function
       (funcall treesit-language-at-point-function position)
     (when-let ((parser (car (treesit-parser-list))))
@@ -374,7 +374,7 @@ to change.  Use `treesit-range-rules' to set this 
variable.")
 (defun treesit-range-rules (&rest query-specs)
   "Produce settings for `treesit-range-settings'.
 
-QUERY-SPECS contains a series of QUERY-SPEC of the form
+QUERY-SPECS are a series of QUERY-SPEC triplets of the form
 
     :KEYWORD VALUE... QUERY
 
@@ -396,8 +396,8 @@ computes the ranges spanned by the captured nodes, and 
applies
 these ranges to parsers for the embedded language.
 
 QUERY can also be a function that takes two arguments, START and
-END.  If QUERY is a function, it doesn't need :KEYWORD VALUE
-pairs preceding it.  This function should set the ranges for
+END.  If QUERY is a function, it doesn't need the :KEYWORD VALUE
+pair preceding it.  This function should set the ranges for
 parsers in the current buffer in the region between START and
 END.  It is OK for this function to set ranges in a larger region
 that encompasses the region between START and END."
@@ -562,7 +562,7 @@ t, nil, append, prepend, keep.  See more in
 (defun treesit-font-lock-rules (&rest query-specs)
   "Return a value suitable for `treesit-font-lock-settings'.
 
-QUERY-SPECS is made of a series of QUERY-SPECs of the form
+QUERY-SPECS is a series of 3 arguments:
 
    :KEYWORD VALUE... QUERY
 
@@ -570,7 +570,7 @@ QUERY is a tree-sitter query in either the string, 
s-expression
 or compiled form.  For each query, captured nodes are highlighted
 with the capture name as its face.
 
-Before each QUERY there could be :KEYWORD VALUE pairs that
+Before each QUERY there could be :KEYWORD and VALUE pairs that
 configure the query (and only that query).  For example,
 
     (treesit-font-lock-rules