mirror of
https://github.com/neovim/neovim.git
synced 2025-11-16 07:11:20 +00:00
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.
This commit is contained in:
Gregory Anders
@@ -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)
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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()
|
||||
|
||||
Reference in New Issue
Block a user