docs: fix vim.treesitter tags

Problem:
Help tags like vim.treesitter.language.add() are confusing because
`vim.treesitter.language` is (thankfully) not a user-facing module.

Solution:
Ignore the "fstem" when generating "treesitter" tags.

runtime/doc/deprecated.txt

@@ -120,7 +120,7 @@ LSP FUNCTIONS
 					or |vim.lsp.buf.format()| instead.
 
 TREESITTER FUNCTIONS
-- *vim.treesitter.language.require_language()*	Use |vim.treesitter.language.add()|
+- *vim.treesitter.language.require_language()*	Use |vim.treesitter.add()|
 						instead.
 - *vim.treesitter.get_node_at_pos()*		Use |vim.treesitter.get_node()|
 						instead.

runtime/doc/news.txt

@@ -162,11 +162,10 @@ The following new APIs or features were added.
 • Treesitter captures can now be transformed by directives. This will allow
   more complicated dynamic language injections.
 
-• |vim.treesitter.query.get_node_text()| now accepts a `metadata` option for
+• |vim.treesitter.get_node_text()| now accepts a `metadata` option for
-  writing custom directives using |vim.treesitter.query.add_directive()|.
+  writing custom directives using |vim.treesitter.add_directive()|.
 
-• |vim.treesitter.language.add()| as a new replacement for
+• |vim.treesitter.add()| replaces `vim.treesitter.language.require_language`.
-  `vim.treesitter.language.require_language`.
 
 • `require'bit'` is now always available |lua-bit|
 
@@ -225,8 +224,7 @@ DEPRECATIONS                                                *news-deprecations*
 The following functions are now deprecated and will be removed in the next
 release.
 
-• `vim.treesitter.language.require_language()` has been deprecated in favour
+• |vim.treesitter.add()| replaces `vim.treesitter.language.require_language()`
-  of |vim.treesitter.language.add()|.
 
 • |vim.treesitter.get_node_at_pos()| and |vim.treesitter.get_node_at_cursor()|
   are both deprecated in favor of |vim.treesitter.get_node()|.

runtime/doc/treesitter.txt

@@ -272,9 +272,8 @@ The following predicates are built in:
 Each predicate has a `not-` prefixed predicate that is just the negation of
 the predicate.
 
-Further predicates can be added via |vim.treesitter.query.add_predicate()|.
+Further predicates can be added via |vim.treesitter.add_predicate()|.
-Use |vim.treesitter.query.list_predicates()| to list all available
+Use |vim.treesitter.list_predicates()| to list all available predicates.
-predicates.
 
 
 TREESITTER QUERY DIRECTIVES                            *treesitter-directives*
@@ -316,9 +315,8 @@ The following directives are built in:
             ((identifier) @constant (#offset! @constant 0 1 0 -1))
 <
 
-Further directives can be added via |vim.treesitter.query.add_directive()|.
+Further directives can be added via |vim.treesitter.add_directive()|.
-Use |vim.treesitter.query.list_directives()| to list all available
+Use |vim.treesitter.list_directives()| to list all available directives.
-directives.
 
 
 TREESITTER QUERY MODELINES                          *treesitter-query-modeline*
@@ -690,7 +688,7 @@ stop({bufnr})                                          *vim.treesitter.stop()*
 ==============================================================================
 Lua module: vim.treesitter.language                  *lua-treesitter-language*
 
-add({lang}, {opts})                            *vim.treesitter.language.add()*
+add({lang}, {opts})                                     *vim.treesitter.add()*
     Asserts that a parser for the language {lang} is installed.
 
     Parsers are searched in the `parser` runtime directory, or the provided
@@ -708,14 +706,14 @@ add({lang}, {opts})                            *vim.treesitter.language.add()*
                 • symbol_name (string|nil) Internal symbol name for the
                   language to load
 
-get_lang({filetype})                      *vim.treesitter.language.get_lang()*
+get_lang({filetype})                               *vim.treesitter.get_lang()*
     Parameters: ~
       • {filetype}  (string)
 
     Return: ~
         (string|nil)
 
-inspect_language({lang})          *vim.treesitter.language.inspect_language()*
+inspect_language({lang})                   *vim.treesitter.inspect_language()*
     Inspects the provided language.
 
     Inspecting provides some useful information on the language like node
@@ -727,7 +725,7 @@ inspect_language({lang})          *vim.treesitter.language.inspect_language()*
     Return: ~
         (table)
 
-register({lang}, {filetype})              *vim.treesitter.language.register()*
+register({lang}, {filetype})                       *vim.treesitter.register()*
     Register a lang to be used for a filetype (or list of filetypes).
 
     Parameters: ~
@@ -738,7 +736,7 @@ register({lang}, {filetype})              *vim.treesitter.language.register()*
 ==============================================================================
 Lua module: vim.treesitter.query                        *lua-treesitter-query*
 
-                                        *vim.treesitter.query.add_directive()*
+                                              *vim.treesitter.add_directive()*
 add_directive({name}, {handler}, {force})
     Adds a new directive to be used in queries
 
@@ -760,7 +758,7 @@ add_directive({name}, {handler}, {force})
                      the predicate `{ "#set!", "conceal", "-" }`
       • {force}    (boolean|nil)
 
-                                        *vim.treesitter.query.add_predicate()*
+                                              *vim.treesitter.add_predicate()*
 add_predicate({name}, {handler}, {force})
     Adds a new predicate to be used in queries
 
@@ -768,11 +766,11 @@ add_predicate({name}, {handler}, {force})
       • {name}     (string) Name of the predicate, without leading #
       • {handler}  function(match:table<string,|TSNode|>, pattern:string,
                    bufnr:number, predicate:string[])
-                   • see |vim.treesitter.query.add_directive()| for argument
+                   • see |vim.treesitter.add_directive()| for argument
                      meanings
       • {force}    (boolean|nil)
 
-                                        *vim.treesitter.query.get_node_text()*
+                                              *vim.treesitter.get_node_text()*
 get_node_text({node}, {source}, {opts})
     Gets the text corresponding to a given node
 
@@ -785,12 +783,12 @@ get_node_text({node}, {source}, {opts})
                     true)
                   • metadata (table) Metadata of a specific capture. This
                     would be set to `metadata[capture_id]` when using
-                    |vim.treesitter.query.add_directive()|.
+                    |vim.treesitter.add_directive()|.
 
     Return: ~
         (string[]|string|nil)
 
-get_query({lang}, {query_name})             *vim.treesitter.query.get_query()*
+get_query({lang}, {query_name})                   *vim.treesitter.get_query()*
     Returns the runtime query {query_name} for {lang}.
 
     Parameters: ~
@@ -800,7 +798,7 @@ get_query({lang}, {query_name})             *vim.treesitter.query.get_query()*
     Return: ~
         Query|nil Parsed query
 
-                                      *vim.treesitter.query.get_query_files()*
+                                            *vim.treesitter.get_query_files()*
 get_query_files({lang}, {query_name}, {is_included})
     Gets the list of files used to make up a query
 
@@ -814,19 +812,19 @@ get_query_files({lang}, {query_name}, {is_included})
         string[] query_files List of files to load for given query and
         language
 
-list_directives()                     *vim.treesitter.query.list_directives()*
+list_directives()                           *vim.treesitter.list_directives()*
     Lists the currently available directives to use in queries.
 
     Return: ~
         string[] List of supported directives.
 
-list_predicates()                     *vim.treesitter.query.list_predicates()*
+list_predicates()                           *vim.treesitter.list_predicates()*
     Lists the currently available predicates to use in queries.
 
     Return: ~
         string[] List of supported predicates.
 
-parse_query({lang}, {query})              *vim.treesitter.query.parse_query()*
+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).
 
@@ -915,8 +913,7 @@ Query:iter_matches({self}, {node}, {source}, {start}, {stop})
         (fun(): integer, table<integer,TSNode>, table): pattern id, match,
         metadata
 
-                                            *vim.treesitter.query.set_query()*
+set_query({lang}, {query_name}, {text})           *vim.treesitter.set_query()*
-set_query({lang}, {query_name}, {text})
     Sets the runtime query named {query_name} for {lang}
 
     This allows users to override any runtime files and/or configuration set
@@ -931,17 +928,6 @@ set_query({lang}, {query_name}, {text})
 ==============================================================================
 Lua module: vim.treesitter.highlighter            *lua-treesitter-highlighter*
 
-new({tree}, {opts})                         *vim.treesitter.highlighter.new()*
-    Creates a new highlighter using
-
-    Parameters: ~
-      • {tree}  |LanguageTree| parser object to use for highlighting
-      • {opts}  (table|nil) Configuration of the highlighter:
-                • queries table overwrite queries used by the highlighter
-
-    Return: ~
-        TSHighlighter Created highlighter object
-
 TSHighlighter:destroy({self})                        *TSHighlighter:destroy()*
     Removes all internal references to the highlighter
 
@@ -1103,21 +1089,4 @@ LanguageTree:trees({self})                              *LanguageTree:trees()*
     Parameters: ~
       • {self}
 
-new({source}, {lang}, {opts})              *vim.treesitter.languagetree.new()*
-    A |LanguageTree| holds the treesitter parser for a given language {lang}
-    used to parse a buffer. As the buffer may contain injected languages, the LanguageTree needs to store parsers for these child languages as well (which in turn
-    may contain child languages themselves, hence the name).
-
-    Parameters: ~
-      • {source}  (integer|string) Buffer or a string of text to parse
-      • {lang}    (string) Root language this tree represents
-      • {opts}    (table|nil) Optional keyword arguments:
-                  • injections table Mapping language to injection query
-                    strings. This is useful for overriding the built-in
-                    runtime file searching for the injection language query
-                    per language.
-
-    Return: ~
-        |LanguageTree| parser object
-
  vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl:

runtime/lua/vim/treesitter/highlighter.lua

@@ -58,7 +58,9 @@ function TSHighlighterQuery:query()
   return self._query
 end
 
---- Creates a new highlighter using @param tree
+---@private
+---
+--- Creates a highlighter for `tree`.
 ---
 ---@param tree LanguageTree parser object to use for highlighting
 ---@param opts (table|nil) Configuration of the highlighter:

runtime/lua/vim/treesitter/languagetree.lua

@@ -38,18 +38,16 @@ local LanguageTree = {}
 
 LanguageTree.__index = LanguageTree
 
---- A |LanguageTree| holds the treesitter parser for a given language {lang} used
+--- @private
---- to parse a buffer. As the buffer may contain injected languages, the LanguageTree
---- needs to store parsers for these child languages as well (which in turn may contain
---- child languages themselves, hence the name).
 ---
----@param source (integer|string) Buffer or a string of text to parse
+--- |LanguageTree| contains a tree of parsers: the root treesitter parser for {lang} and any
----@param lang string Root language this tree represents
+--- "injected" language parsers, which themselves may inject other languages, recursively.
----@param opts (table|nil) Optional keyword arguments:
+---
----             - injections table Mapping language to injection query strings.
+---@param source (integer|string) Buffer or text string to parse
----                                This is useful for overriding the built-in
+---@param lang string Root language of this tree
----                                runtime file searching for the injection language
+---@param opts (table|nil) Optional arguments:
----                                query per language.
+---             - injections table Map of language to injection query strings. Overrides the
+---                                built-in runtime file searching for language injections.
 ---@return LanguageTree parser object
 function LanguageTree.new(source, lang, opts)
   language.add(lang)

runtime/lua/vim/treesitter/query.lua

@@ -273,8 +273,7 @@ end
 ---@param opts (table|nil) Optional parameters.
 ---          - concat: (boolean) Concatenate result in a string (default true)
 ---          - metadata (table) Metadata of a specific capture. This would be
----            set to `metadata[capture_id]` when using
+---            set to `metadata[capture_id]` when using |vim.treesitter.add_directive()|.
----            |vim.treesitter.query.add_directive()|.
 ---@return (string[]|string|nil)
 function M.get_node_text(node, source, opts)
   opts = opts or {}
@@ -486,7 +485,7 @@ local directive_handlers = {
 ---
 ---@param name string Name of the predicate, without leading #
 ---@param handler function(match:table<string,TSNode>, pattern:string, bufnr:number, predicate:string[])
----   - see |vim.treesitter.query.add_directive()| for argument meanings
+---   - see |vim.treesitter.add_directive()| for argument meanings
 ---@param force boolean|nil
 function M.add_predicate(name, handler, force)
   if predicate_handlers[name] and not force then

scripts/gen_vimdoc.py

@@ -286,7 +286,7 @@ CONFIG = {
             if fstem == 'treesitter'
             else f'*{name}()*'
             if name[0].isupper()
-            else f'*vim.treesitter.{fstem}.{name}()*'),
+            else f'*vim.treesitter.{name}()*'),
         'module_override': {},
         'append_only': [],
     }

scripts/lua2dox.lua

@@ -27,7 +27,10 @@ http://search.cpan.org/~alec/Doxygen-Lua-0.02/lib/Doxygen/Lua.pm
 Running
 -------
 
-This script "lua2dox.lua" gets called by "gen_vimdoc.py".
+This script "lua2dox.lua" gets called by "gen_vimdoc.py". To debug, run gen_vimdoc.py with
+--keep-tmpfiles:
+
+    python3 scripts/gen_vimdoc.py -t treesitter --keep-tmpfiles
 
 Doxygen must be on your system. You can experiment like so:
 
@@ -71,14 +74,14 @@ local function class()
   return newClass
 end
 
---! \brief write to stdout
+-- write to stdout
 local function TCore_IO_write(Str)
   if Str then
     io.write(Str)
   end
 end
 
---! \brief write to stdout
+-- write to stdout
 local function TCore_IO_writeln(Str)
   if Str then
     io.write(Str)
@@ -86,12 +89,12 @@ local function TCore_IO_writeln(Str)
   io.write('\n')
 end
 
---! \brief trims a string
+-- trims a string
 local function string_trim(Str)
   return Str:match('^%s*(.-)%s*$')
 end
 
---! \brief split a string
+-- split a string
 --!
 --! \param Str
 --! \param Pattern
@@ -117,12 +120,12 @@ local function string_split(Str, Pattern)
 end
 
 -------------------------------
---! \brief file buffer
+-- file buffer
 --!
 --! an input file buffer
 local TStream_Read = class()
 
---! \brief get contents of file
+-- get contents of file
 --!
 --! \param Filename name of file to read (or nil == stdin)
 function TStream_Read.getContents(this, Filename)
@@ -143,12 +146,12 @@ function TStream_Read.getContents(this, Filename)
   return filecontents
 end
 
---! \brief get lineno
+-- get lineno
 function TStream_Read.getLineNo(this)
   return this.currentLineNo
 end
 
---! \brief get a line
+-- get a line
 function TStream_Read.getLine(this)
   local line
   if this.currentLine then
@@ -166,12 +169,12 @@ function TStream_Read.getLine(this)
   return line
 end
 
---! \brief save line fragment
+-- save line fragment
 function TStream_Read.ungetLine(this, LineFrag)
   this.currentLine = LineFrag
 end
 
---! \brief is it eof?
+-- is it eof?
 function TStream_Read.eof(this)
   if this.currentLine or this.currentLineNo <= this.contentsLen then
     return false
@@ -179,31 +182,31 @@ function TStream_Read.eof(this)
   return true
 end
 
---! \brief output stream
+-- output stream
 local TStream_Write = class()
 
---! \brief constructor
+-- constructor
 function TStream_Write.init(this)
   this.tailLine = {}
 end
 
---! \brief write immediately
+-- write immediately
 function TStream_Write.write(_, Str)
   TCore_IO_write(Str)
 end
 
---! \brief write immediately
+-- write immediately
 function TStream_Write.writeln(_, Str)
   TCore_IO_writeln(Str)
 end
 
---! \brief write immediately
+-- write immediately
 function TStream_Write.writelnComment(_, Str)
   TCore_IO_write('// ZZ: ')
   TCore_IO_writeln(Str)
 end
 
---! \brief write to tail
+-- write to tail
 function TStream_Write.writelnTail(this, Line)
   if not Line then
     Line = ''
@@ -211,7 +214,7 @@ function TStream_Write.writelnTail(this, Line)
   table.insert(this.tailLine, Line)
 end
 
---! \brief output tail lines
+-- output tail lines
 function TStream_Write.write_tailLines(this)
   for _, line in ipairs(this.tailLine) do
     TCore_IO_writeln(line)
@@ -219,17 +222,17 @@ function TStream_Write.write_tailLines(this)
   TCore_IO_write('// Lua2DoX new eof')
 end
 
---! \brief input filter
+-- input filter
 local TLua2DoX_filter = class()
 
---! \brief allow us to do errormessages
+-- allow us to do errormessages
 function TLua2DoX_filter.warning(this, Line, LineNo, Legend)
   this.outStream:writelnTail(
     '//! \todo warning! ' .. Legend .. ' (@' .. LineNo .. ')"' .. Line .. '"'
   )
 end
 
---! \brief trim comment off end of string
+-- trim comment off end of string
 --!
 --! If the string has a comment on the end, this trims it off.
 --!
@@ -243,7 +246,7 @@ local function TString_removeCommentFromLine(Line)
   return Line, tailComment
 end
 
---! \brief get directive from magic
+-- get directive from magic
 local function getMagicDirective(Line)
   local macro, tail
   local macroStr = '[\\@]'
@@ -264,7 +267,7 @@ local function getMagicDirective(Line)
   return macro, tail
 end
 
---! \brief check comment for fn
+-- check comment for fn
 local function checkComment4fn(Fn_magic, MagicLines)
   local fn_magic = Fn_magic
   --    TCore_IO_writeln('// checkComment4fn "' .. MagicLines .. '"')
@@ -293,7 +296,7 @@ local tagged_types = { 'TSNode', 'LanguageTree' }
 -- Document these as 'table'
 local alias_types = { 'Range4', 'Range6' }
 
---! \brief run the filter
+-- run the filter
 function TLua2DoX_filter.readfile(this, AppStamp, Filename)
   local inStream = TStream_Read()
   local outStream = TStream_Write()
@@ -524,10 +527,10 @@ function TLua2DoX_filter.readfile(this, AppStamp, Filename)
   end
 end
 
---! \brief this application
+-- this application
 local TApp = class()
 
---! \brief constructor
+-- constructor
 function TApp.init(this)
   this.timestamp = os.date('%c %Z', os.time())
   this.name = 'Lua2DoX'