Merge pull request #13229 from ElPiloto/more_treesitter_doc

[RDY] doc: Supplement documentation for treesitter.

1 files changed, 17 insertions, 0 deletions

diff --git a/runtime/doc/treesitter.txt b/runtime/doc/treesitter.txt
index 072f2cd074..58cd535e98 100644
--- a/runtime/doc/treesitter.txt
+++ b/runtime/doc/treesitter.txt
@@ -164,11 +164,28 @@ Tree-sitter queries are supported, with some limitations. Currently, the only
 supported match predicate is `eq?` (both comparing a capture against a string
 and two captures against each other).
 
+A `query` consists of one or more patterns. A `pattern` is defined over node
+types in the syntax tree.  A `match` corresponds to specific elements of the
+syntax tree which match a pattern. Patterns may optionally define captures
+and predicates. A `capture` allows you to associate names with a specific
+node in a pattern. A `predicate` adds arbitrary metadata and conditional data
+to a match.
+
 vim.treesitter.parse_query({lang}, {query})
 						*vim.treesitter.parse_query()*
 	Parse {query} as a string. (If the query is in a file, the caller
         should read the contents into a string before calling).
 
+	Returns a `Query` (see |lua-treesitter-query|) object which can be used to
+	search nodes in the syntax tree for the patterns defined in {query}
+	using `iter_*` methods below. Exposes `info` and `captures` with
+	additional information about the {query}.
+	  - `captures` contains the list of unique capture names defined in
+	    {query}.
+	  -` info.captures` also points to `captures`.
+	  - `info.patterns` contains information about predicates.
+
+
 query:iter_captures({node}, {bufnr}, {start_row}, {end_row})
 							*query:iter_captures()*
 	Iterate over all captures from all matches inside {node}.