; Fix documentation of recent treesit changes

* src/treesit.c (Ftreesit_query_capture)
(Ftreesit_parser_embed_level, Ftreesit_parser_set_embed_level)
(Ftreesit_parser_set_parent_node):
* lisp/treesit.el (treesit-query-range)
(treesit-query-range-by-language, treesit-range-settings)
(treesit-range-rules, treesit--parser-at-level)
(treesit--update-ranges-non-local, treesit--update-ranges-local)
(treesit--update-range-1): Fix wording and typos in doc strings.

* doc/lispref/parsing.texi (Pattern Matching): Fix wording.

4 files changed, 39 insertions, 36 deletions

diff --git a/doc/lispref/parsing.texi b/doc/lispref/parsing.texi
index 2b224036de0..ade7b819756 100644
--- a/doc/lispref/parsing.texi
+++ b/doc/lispref/parsing.texi
@@ -1247,9 +1247,8 @@ matching node whose span overlaps with the region between @var{beg}
 and @var{end} is captured; it doesn't have to be completely contained
 in the region.
 
-If @var{grouped} is non-@code{nil}, instead of returning a list of
-@w{@code{(@var{capture_name} . @var{node})}}, this function returns a
-list of list of it.  The grouping is determined by @var{query}.
+If @var{grouped} is non-@code{nil}, this function returns a grouped list
+of lists of captured nodes.  The grouping is determined by @var{query}.
 Captures in the same match of a pattern in @var{query} are grouped
 together.
 
diff --git a/lisp/treesit.el b/lisp/treesit.el
index e05e3526c15..e958b2cad64 100644
--- a/lisp/treesit.el
+++ b/lisp/treesit.el
@@ -153,7 +153,7 @@ of max unsigned 32-bit value for byte offsets into buffer text."
 
 ;;; Parser API supplement
 
-;; The primary parser will be access frequently (after each re-parse,
+;; The primary parser will be accessed frequently (after each re-parse,
 ;; before redisplay, etc, see
 ;; `treesit--font-lock-mark-ranges-to-fontify'), so we don't want to
 ;; allow it to be a callback function which returns the primary parser
@@ -559,8 +559,8 @@ respective offset values are added to each (START . END) range
 being returned.  Capture names generally don't matter, but names
 that starts with an underscore are ignored.
 
-RANGE-FN, if non-nil, is a function that takes a node and OFFSET, and
-returns the ranges to use for that node."
+RANGE-FN, if non-nil, is a function that takes a NODE and OFFSET, and
+returns the ranges to use for that NODE."
   (let ((offset-left (or (car offset) 0))
         (offset-right (or (cdr offset) 0)))
     (cl-loop for capture
@@ -585,8 +585,8 @@ Query NODE with QUERY, the captured nodes generates ranges.  Nodes
 captured by the `@language' capture name are converted to language
 symbols with LANGUAGE-FN.
 
-RANGE-FN, if non-nil, is a function that takes a node and OFFSET, and
-returns the ranges to use for that node.
+RANGE-FN, if non-nil, is a function that takes a NODE and OFFSET, and
+returns the ranges to use for that NODE.
 
 BEG, END, OFFSET are the same as in `treesit-query-range'."
   (let ((offset-left (or (car offset) 0))
@@ -644,13 +644,13 @@ using a single parser for all the ranges.  If OFFSET is non-nil, it
 should be a cons of numbers (START-OFFSET . END-OFFSET), where the start
 and end offset are added to each queried range to get the result ranges.
 
-If RANGE-FN is non-nil, it should be a function, Emacs uses this
+If RANGE-FN is non-nil, it should be a function; Emacs uses this
 function to compute the ranges to use for the embedded parser.  The
 function is passed the captured node and OFFSET, and should return a
 list of ranges, where each range is a cons of the start and end
 position.
 
-Capture names generally don't matter, but names that starts with
+Capture names generally don't matter, but names that start with
 an underscore are ignored.
 
 QUERY can also be a function, in which case it is called with 2
@@ -672,8 +672,8 @@ like this:
 Each QUERY is a tree-sitter query in either the string,
 s-expression or compiled form.
 
-Capture names generally don't matter, but names that starts with an
-underscore are ignored.  And `@language' is reserved.
+Capture names generally don't matter, but names that start with an
+underscore are ignored.  The `@language' capture name is reserved.
 
 For each QUERY, :KEYWORD and VALUE pairs add meta information to
 it.  For example,
@@ -690,8 +690,8 @@ this way: Emacs queries QUERY in the host language's parser,
 computes the ranges spanned by the captured nodes, and applies
 these ranges to parsers for the embedded language.
 
-If the embed language is dynamic, then a function in place of the embed
-language symbol.  This function will by passed a node and should return
+If the embed language is dynamic, then `:embed' can specify a
+function.  This function will by passed a node and should return
 the language symbol for the embedded code block.  The node is the one
 captured from QUERY with capture name `@language'.  Also make sure the
 code block and language capture are in the same match group.
@@ -896,10 +896,10 @@ it."
         (delete-overlay ov)))))
 
 (defsubst treesit--parser-at-level (parsers level &optional include-null)
-  "Filter for parsers in PARSERS that has embed level equal to LEVEL.
+  "Filter for parsers in PARSERS that have embed level equal to LEVEL.
 
-If INCLUDE-NULL is non-nil, also include parsers that has a nil embed
-level."
+If INCLUDE-NULL is non-nil, also include parsers whose embed level
+is nil."
   (seq-filter (lambda (parser)
                 (or (eq (treesit-parser-embed-level parser) level)
                     (and include-null
@@ -918,7 +918,7 @@ Use QUERY to get the ranges, and set ranges for embedded parsers to
 those ranges.  HOST-PARSER and QUERY must match.
 
 EMBED-LANG is either a language symbol or a function that takes a node
-and return a language symbol.
+and returns a language symbol.
 
 EMBED-LEVEL is the embed level for the local parsers being created or
 updated.  When looking for existing local parsers, only look for parsers
@@ -928,7 +928,7 @@ level.
 RANGE-FN, if non-nil, is a function that takes a node and OFFSET, and
 returns the ranges to use for that node.
 
-Return updated parsers in a list."
+Return updated parsers as a list."
   (let ((ranges-by-lang
          (if (functionp embed-lang)
              (treesit-query-range-by-language
@@ -998,7 +998,7 @@ for the local parser.
 RANGE-FN, if non-nil, is a function that takes a node and OFFSET, and
 returns the ranges to use for that node.
 
-Return the created local parsers in a list."
+Return the created local parsers as a list."
   ;; Update range.
   (let ((ranges-by-lang
          (if (functionp embedded-lang)
@@ -1050,8 +1050,8 @@ Return the created local parsers in a list."
   "Given a HOST-PARSER, update ranges between BEG and END.
 
 Go over each settings in SETTINGS, try to create or update the embedded
-language in that setting.  Return the created or updated embedded
-language parsers in a list.
+language in that setting.  Return the list of the created or updated
+embedded language parsers.
 
 EMBED-LEVEL is the embed level for the embedded parser being created or
 updated.  When looking for existing embedded parsers, only look for
diff --git a/src/treesit.c b/src/treesit.c
index c8af17a5b8b..20c3626732a 100644
--- a/src/treesit.c
+++ b/src/treesit.c
@@ -1827,8 +1827,8 @@ DEFUN ("treesit-parser-embed-level",
 
 The embed level can be either nil or a non-negative integer.  A value of
 nil means the parser isn't part of the embedded parser tree.  The
-primary parser has embed level 0, from it, each layer of embedded parser
-has +1 embed level.  */)
+primary parser has embed level 0, and each additional layer of parser
+embedding increments the embed level by 1.  */)
   (Lisp_Object parser)
 {
   treesit_check_parser (parser);
@@ -1839,7 +1839,9 @@ has +1 embed level.  */)
 DEFUN ("treesit-parser-set-embed-level",
        Ftreesit_parser_set_embed_level, Streesit_parser_set_embed_level,
        2, 2, 0,
-       doc: /* Set the embed level for PARSER to LEVEL.  */)
+       doc: /* Set the embed level for PARSER to LEVEL.
+LEVEL can be nil, for a parser that is not part of an embedded parser
+tree; otherwise it must be a non-negative integer.  */)
   (Lisp_Object parser, Lisp_Object level)
 {
   treesit_check_parser (parser);
@@ -1859,7 +1861,7 @@ DEFUN ("treesit-parser-parent-node",
        1, 1, 0,
        doc: /* Return PARSER's parent node, if one exists.
 
-Only embeded local parser can have parent node.  When Emacs uses a node
+Only embeded local parsers can have parent node.  When Emacs uses a node
 in the host parser to create this local parser, that node is considered
 the parent node of the local parser.  */)
   (Lisp_Object parser)
@@ -1871,7 +1873,7 @@ the parent node of the local parser.  */)
 DEFUN ("treesit-parser-set-parent-node",
        Ftreesit_parser_set_parent_node, Streesit_parser_set_parent_node,
        2, 2, 0,
-       doc: /* Return PARSER's parent node to NODE.  */)
+       doc: /* Make NODE be the parent node of PARSER.  */)
   (Lisp_Object parser, Lisp_Object node)
 {
   treesit_check_parser (parser);
@@ -3289,8 +3291,9 @@ in which the query is executed.  Any matching node whose span overlaps
 with the region between BEG and END are captured, it doesn't have to
 be completely in the region.
 
-If GROUPED is non-nil, group captures into matches and return a list of
-MATCH, where each MATH is a list of (CAPTURE_NAME . NODE).
+If GROUPED is non-nil, ther function groups the returned list of
+captures into matches and return a list of MATCH, where each MATCH is
+a list of the form (CAPTURE_NAME . NODE).
 
 If NODE-ONLY is non-nil, return nodes only, and don't include
 CAPTURE_NAME.
diff --git a/src/treesit.h b/src/treesit.h
index d19a0e76216..d4cfc47ee5d 100644
--- a/src/treesit.h
+++ b/src/treesit.h
@@ -64,12 +64,13 @@ struct Lisp_TS_Parser
      = 0, end_byte = UINT32_MAX).  */
   Lisp_Object last_set_ranges;
   /* Parsers for embedded code blocks will have a non-zero embed level.
-     The primary parser has level 0, and each layer of embedded parser
-     gets +1 level.  The embed level can be either a non-negative
-     integer or nil.  Every parser created by treesit-parser-create
-     starts with a nil level.  If the value is nil, that means the range
-     functions (treesit-update-ranges and friends) haven't touched this
-     parser yet, and this parser isn't part of the embed parser tree.  */
+     The primary parser has level 0, and each additional layer of parser
+     embedding increments the leve by 1.  The embed level can be either
+     a non-negative integer or nil.  Every parser created by
+     'treesit-parser-create' starts with a nil level.  If the value is
+     nil, that means the range functions (treesit-update-ranges and
+     friends) haven't touched this parser yet, and this parser isn't
+     part of the embed parser tree.  */
   Lisp_Object embed_level;
   /* Some comments: Technically you could calculate embed_level by
      following parent_node, but parent_node might be outdated so it's a
@@ -80,7 +81,7 @@ struct Lisp_TS_Parser
      for a parser will be useful beyond this.  And we can always convert
      these to properties later, but not vice versa.  */
   /* When an embedded parser is created, it's usually based on a node in
-     the host parser.  This field saves that node so it possible to
+     the host parser.  This field saves that node so it's possible to
      climb up and out of the embedded parser into the host parser.  Note
      that the range of the embedded parser doesn't have to match that of
      the parent node.  */