docs: make Lua docstrings consistent #15255

The official developer documentation in in :h dev-lua-doc specifies to
use "--@" for special/magic tokens. However, this format is not
consistent with EmmyLua notation (used by some Lua language servers) nor
with the C version of the magic docstring tokens which use three comment
characters.

Further, the code base is currently split between usage of "--@",
"---@", and "--- @". In an effort to remain consistent, change all Lua
magic tokens to use "---@" and update the developer documentation
accordingly.

4 files changed, 58 insertions, 58 deletions

diff --git a/runtime/lua/vim/treesitter/highlighter.lua b/runtime/lua/vim/treesitter/highlighter.lua
index bf5bd791c3..22b528838c 100644
--- a/runtime/lua/vim/treesitter/highlighter.lua
+++ b/runtime/lua/vim/treesitter/highlighter.lua
@@ -122,8 +122,8 @@ end
 
 --- Creates a new highlighter using @param tree
 ---
---- @param tree The language tree to use for highlighting
---- @param opts Table used to configure the highlighter
+---@param tree The language tree to use for highlighting
+---@param opts Table used to configure the highlighter
 ---           - queries: Table to overwrite queries used by the highlighter
 function TSHighlighter.new(tree, opts)
   local self = setmetatable({}, TSHighlighter)
@@ -217,7 +217,7 @@ end
 
 --- Gets the query used for @param lang
 ---
---- @param lang A language used by the highlighter.
+---@param lang A language used by the highlighter.
 function TSHighlighter:get_query(lang)
   if not self._queries[lang] then
     self._queries[lang] = TSHighlighterQuery.new(lang)
diff --git a/runtime/lua/vim/treesitter/language.lua b/runtime/lua/vim/treesitter/language.lua
index 6dc37c7848..89ddd6cd5a 100644
--- a/runtime/lua/vim/treesitter/language.lua
+++ b/runtime/lua/vim/treesitter/language.lua
@@ -6,9 +6,9 @@ local M = {}
 ---
 --- Parsers are searched in the `parser` runtime directory.
 ---
---- @param lang The language the parser should parse
---- @param path Optional path the parser is located at
---- @param silent Don't throw an error if language not found
+---@param lang The language the parser should parse
+---@param path Optional path the parser is located at
+---@param silent Don't throw an error if language not found
 function M.require_language(lang, path, silent)
   if vim._ts_has_language(lang) then
     return true
@@ -40,7 +40,7 @@ end
 ---
 --- Inspecting provides some useful informations on the language like node names, ...
 ---
---- @param lang The language.
+---@param lang The language.
 function M.inspect_language(lang)
   M.require_language(lang)
   return vim._ts_inspect_language(lang)
diff --git a/runtime/lua/vim/treesitter/languagetree.lua b/runtime/lua/vim/treesitter/languagetree.lua
index 899d90e464..7e392f72a4 100644
--- a/runtime/lua/vim/treesitter/languagetree.lua
+++ b/runtime/lua/vim/treesitter/languagetree.lua
@@ -9,12 +9,12 @@ LanguageTree.__index = LanguageTree
 --- The language can contain child languages with in its range,
 --- hence the tree.
 ---
---- @param source Can be a bufnr or a string of text to parse
---- @param lang The language this tree represents
---- @param opts Options table
---- @param opts.injections A table of language to injection query strings.
----                        This is useful for overriding the built-in runtime file
----                        searching for the injection language query per language.
+---@param source Can be a bufnr or a string of text to parse
+---@param lang The language this tree represents
+---@param opts Options table
+---@param opts.injections A table of language to injection query strings.
+---                      This is useful for overriding the built-in runtime file
+---                      searching for the injection language query per language.
 function LanguageTree.new(source, lang, opts)
   language.require_language(lang)
   opts = opts or {}
@@ -171,8 +171,8 @@ end
 
 --- Invokes the callback for each LanguageTree and it's children recursively
 ---
---- @param fn The function to invoke. This is invoked with arguments (tree: LanguageTree, lang: string)
---- @param include_self Whether to include the invoking tree in the results.
+---@param fn The function to invoke. This is invoked with arguments (tree: LanguageTree, lang: string)
+---@param include_self Whether to include the invoking tree in the results.
 function LanguageTree:for_each_child(fn, include_self)
   if include_self then
     fn(self, self._lang)
@@ -187,8 +187,8 @@ end
 ---
 --- Note, this includes the invoking language tree's trees as well.
 ---
---- @param fn The callback to invoke. The callback is invoked with arguments
----           (tree: TSTree, languageTree: LanguageTree)
+---@param fn The callback to invoke. The callback is invoked with arguments
+---         (tree: TSTree, languageTree: LanguageTree)
 function LanguageTree:for_each_tree(fn)
   for _, tree in ipairs(self._trees) do
     fn(tree, self)
@@ -203,7 +203,7 @@ end
 ---
 --- If the language already exists as a child, it will first be removed.
 ---
---- @param lang The language to add.
+---@param lang The language to add.
 function LanguageTree:add_child(lang)
   if self._children[lang] then
     self:remove_child(lang)
@@ -219,7 +219,7 @@ end
 
 --- Removes a child language from this tree.
 ---
---- @param lang The language to remove.
+---@param lang The language to remove.
 function LanguageTree:remove_child(lang)
   local child = self._children[lang]
 
@@ -259,7 +259,7 @@ end
 ---
 --- Note, this call invalidates the tree and requires it to be parsed again.
 ---
---- @param regions A list of regions this tree should manage and parse.
+---@param regions A list of regions this tree should manage and parse.
 function LanguageTree:set_included_regions(regions)
   -- TODO(vigoux): I don't think string parsers are useful for now
   if type(self._source) == "number" then
@@ -299,7 +299,7 @@ end
 ---
 --- TODO: Allow for an offset predicate to tailor the injection range
 ---       instead of using the entire nodes range.
---- @private
+---@private
 function LanguageTree:_get_injections()
   if not self._injection_query then return {} end
 
@@ -449,7 +449,7 @@ function LanguageTree:_on_detach(...)
 end
 
 --- Registers callbacks for the parser
---- @param cbs An `nvim_buf_attach`-like table argument with the following keys :
+---@param cbs An `nvim_buf_attach`-like table argument with the following keys :
 ---  `on_bytes` : see `nvim_buf_attach`, but this will be called _after_ the parsers callback.
 ---  `on_changedtree` : a callback that will be called every time the tree has syntactical changes.
 ---      it will only be passed one argument, that is a table of the ranges (as node ranges) that
@@ -497,7 +497,7 @@ end
 ---
 --- This goes down the tree to recursively check childs.
 ---
---- @param range A range, that is a `{ start_line, start_col, end_line, end_col }` table.
+---@param range A range, that is a `{ start_line, start_col, end_line, end_col }` table.
 function LanguageTree:contains(range)
   for _, tree in pairs(self._trees) do
     if tree_contains(tree, range) then
@@ -510,7 +510,7 @@ end
 
 --- Gets the appropriate language that contains @param range
 ---
---- @param range A text range, see |LanguageTree:contains|
+---@param range A text range, see |LanguageTree:contains|
 function LanguageTree:language_for_range(range)
   for _, child in pairs(self._children) do
     if child:contains(range) then
diff --git a/runtime/lua/vim/treesitter/query.lua b/runtime/lua/vim/treesitter/query.lua
index 4ecd91d295..66da179ea3 100644
--- a/runtime/lua/vim/treesitter/query.lua
+++ b/runtime/lua/vim/treesitter/query.lua
@@ -36,9 +36,9 @@ end
 
 --- Gets the list of files used to make up a query
 ---
---- @param lang The language
---- @param query_name The name of the query to load
---- @param is_included Internal parameter, most of the time left as `nil`
+---@param lang The language
+---@param query_name The name of the query to load
+---@param is_included Internal parameter, most of the time left as `nil`
 function M.get_query_files(lang, query_name, is_included)
   local query_path = string.format('queries/%s/%s.scm', lang, query_name)
   local lang_files = dedupe_files(a.nvim_get_runtime_file(query_path, true))
@@ -112,19 +112,19 @@ local explicit_queries = setmetatable({}, {
 --- This allows users to override any runtime files and/or configuration
 --- set by plugins.
 ---
---- @param lang string: The language to use for the query
---- @param query_name string: The name of the query (i.e. "highlights")
---- @param text string: The query text (unparsed).
+---@param lang string: The language to use for the query
+---@param query_name string: The name of the query (i.e. "highlights")
+---@param text string: The query text (unparsed).
 function M.set_query(lang, query_name, text)
   explicit_queries[lang][query_name] = M.parse_query(lang, text)
 end
 
 --- Returns the runtime query {query_name} for {lang}.
 ---
---- @param lang The language to use for the query
---- @param query_name The name of the query (i.e. "highlights")
+---@param lang The language to use for the query
+---@param query_name The name of the query (i.e. "highlights")
 ---
---- @return The corresponding query, parsed.
+---@return The corresponding query, parsed.
 function M.get_query(lang, query_name)
   if explicit_queries[lang][query_name] then
     return explicit_queries[lang][query_name]
@@ -151,10 +151,10 @@ end
 ---   -` info.captures` also points to `captures`.
 ---   - `info.patterns` contains information about predicates.
 ---
---- @param lang The language
---- @param query A string containing the query (s-expr syntax)
+---@param lang The language
+---@param query A string containing the query (s-expr syntax)
 ---
---- @returns The query
+---@returns The query
 function M.parse_query(lang, query)
   language.require_language(lang)
   local self = setmetatable({}, Query)
@@ -168,8 +168,8 @@ end
 
 --- Gets the text corresponding to a given node
 ---
---- @param node the node
---- @param bsource The buffer or string from which the node is extracted
+---@param node the node
+---@param bsource The buffer or string from which the node is extracted
 function M.get_node_text(node, source)
   local start_row, start_col, start_byte = node:start()
   local end_row, end_col, end_byte = node:end_()
@@ -327,9 +327,9 @@ local directive_handlers = {
 
 --- Adds a new predicate to be used in queries
 ---
---- @param name the name of the predicate, without leading #
---- @param handler the handler function to be used
----    signature will be (match, pattern, bufnr, predicate)
+---@param name the name of the predicate, without leading #
+---@param handler the handler function to be used
+---      signature will be (match, pattern, bufnr, predicate)
 function M.add_predicate(name, handler, force)
   if predicate_handlers[name] and not force then
     error(string.format("Overriding %s", name))
@@ -340,9 +340,9 @@ end
 
 --- Adds a new directive to be used in queries
 ---
---- @param name the name of the directive, without leading #
---- @param handler the handler function to be used
----    signature will be (match, pattern, bufnr, predicate)
+---@param name the name of the directive, without leading #
+---@param handler the handler function to be used
+---      signature will be (match, pattern, bufnr, predicate)
 function M.add_directive(name, handler, force)
   if directive_handlers[name] and not force then
     error(string.format("Overriding %s", name))
@@ -351,12 +351,12 @@ function M.add_directive(name, handler, force)
   directive_handlers[name] = handler
 end
 
---- @return The list of supported directives.
+---@return The list of supported directives.
 function M.list_directives()
   return vim.tbl_keys(directive_handlers)
 end
 
---- @return The list of supported predicates.
+---@return The list of supported predicates.
 function M.list_predicates()
   return vim.tbl_keys(predicate_handlers)
 end
@@ -465,13 +465,13 @@ end
 --- end
 --- </pre>
 ---
---- @param node The node under which the search will occur
---- @param source The source buffer or string to exctract text from
---- @param start The starting line of the search
---- @param stop The stopping line of the search (end-exclusive)
+---@param node The node under which the search will occur
+---@param source The source buffer or string to exctract text from
+---@param start The starting line of the search
+---@param stop The stopping line of the search (end-exclusive)
 ---
---- @returns The matching capture id
---- @returns The captured node
+---@returns The matching capture id
+---@returns The captured node
 function Query:iter_captures(node, source, start, stop)
   if type(source) == "number" and source == 0 then
     source = vim.api.nvim_get_current_buf()
@@ -522,13 +522,13 @@ end
 --- end
 --- </pre>
 ---
---- @param node The node under which the search will occur
---- @param source The source buffer or string to search
---- @param start The starting line of the search
---- @param stop The stopping line of the search (end-exclusive)
+---@param node The node under which the search will occur
+---@param source The source buffer or string to search
+---@param start The starting line of the search
+---@param stop The stopping line of the search (end-exclusive)
 ---
---- @returns The matching pattern id
---- @returns The matching match
+---@returns The matching pattern id
+---@returns The matching match
 function Query:iter_matches(node, source, start, stop)
   if type(source) == "number" and source == 0 then
     source = vim.api.nvim_get_current_buf()