doc: Supplement documentation for treesitter.

- Describe query components (capture, match, pattern). Not
well-described in tree-sitter documentation.

- Describe Query() object. Not actually described anywhere in
documenation.

1 files changed, 17 insertions, 0 deletions

diff --git a/runtime/doc/treesitter.txt b/runtime/doc/treesitter.txt
index 072f2cd074..8bedc0153e 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| 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}.