Problem
---
If a highlighter query returns a significant number of predicate
non-matches, the highlighter will scan well past the end of the window.

Solution
---
In the iterator returned from `iter_captures`, accept an optional
parameter `end_line`. If no parameter provided, the behavior is
unchanged, hence this is a non-invasive tweak.

Fixes: #25113 nvim-treesitter/nvim-treesitter#5057

Problem:
* The guessed botline might be smaller than the actual botline e.g. when
  there are folds and the user is typing in insert mode. This may result
  in incorrect treesitter highlights for injections.
* botline can be larger than the last line number of the buffer, which
  results in errors when placing extmarks.

Solution:
* Take a more conservative approximation. I am not sure if it is
  sufficient to guarantee correctness, but it seems to be good enough
  for the case mentioned above.
* Clamp it to the last line number.

Co-authored-by: Lewis Russell <me@lewisr.dev>

Problem:

Treesitter highlighting is slow for large files with lots of injections.

Solution:

Only parse injections we are going to render during a redraw cycle.

---

- `LanguageTree:parse()` will no longer parse injections by default and
  now requires an explicit range argument to be passed.

- `TSHighlighter` now parses injections incrementally during on_win
  callbacks for the line range being rendered.

- Plugins which require certain injections to be parsed must run
  `parser:parse({ start_row, end_row })` before using the tree.

* docs(lua): teach lua2dox how to table

* docs(lua): teach gen_vimdoc.py about local functions

No more need to mark local functions with @private

* docs(lua): mention @nodoc and @meta in dev-lua-doc

* fixup!

Co-authored-by: Justin M. Keyes <justinkz@gmail.com>

---------

Co-authored-by: Justin M. Keyes <justinkz@gmail.com>

Problem: Treesitter highlighting base priority cannot be customized.

Solution: Use `vim.highlight.priorities.treesitter` instead of hard-coded value.

When injections are added or removed make sure to:
- invoke 'changedtree' callbacks for when new trees are added.
- invoke 'changedtree' callbacks for when trees are invalidated
- redraw regions when languagetree children are removed

Problem:
  Codebase inconsistently binds vim.api onto a or api.

Solution:
  Use api everywhere. a as an identifier is too short to have at the
  module level.

use `treesitter.get_range` instead of inline expression

The following top level Treesitter functions have been moved:
  - vim.treesitter.inspect_language() -> vim.treesitter.language.inspect()
  - vim.treesitter.get_query_files() -> vim.treesitter.query.get_files()
  - vim.treesitter.set_query() -> vim.treesitter.query.set()
  - vim.treesitter.query.set_query() -> vim.treesitter.query.set()
  - vim.treesitter.get_query() -> vim.treesitter.query.get()
  - vim.treesitter.query.get_query() -> vim.treesitter.query.get()
  - vim.treesitter.parse_query() -> vim.treesitter.query.parse()
  - vim.treesitter.query.parse_query() -> vim.treesitter.query.parse()
  - vim.treesitter.add_predicate() -> vim.treesitter.query.add_predicate()
  - vim.treesitter.add_directive() -> vim.treesitter.query.add_directive()
  - vim.treesitter.list_predicates() -> vim.treesitter.query.list_predicates()
  - vim.treesitter.list_directives() -> vim.treesitter.query.list_directives()
  - vim.treesitter.query.get_range() -> vim.treesitter.get_range()
  - vim.treesitter.query.get_node_text() -> vim.treesitter.get_node_text()

- Begin using `@package` in place of `@private` for functions
that are accessed internally but outside their defined class.

- Rename Node -> TSP.Node