docs: reorder sections #35140

Problem:
Generated docs sections are ordered randomly. This matters when showing
an outline or table of contents (e.g. `gO`).

Solution:
Specify which sections have an intentional ordering; sort the rest by
name.
This commit is contained in:
Justin M. Keyes
2025-08-03 01:03:09 -04:00
committed by GitHub
parent e23794b090
commit 39e402caa5
5 changed files with 3402 additions and 3400 deletions

File diff suppressed because it is too large Load Diff

File diff suppressed because it is too large Load Diff

File diff suppressed because it is too large Load Diff

View File

@@ -1247,6 +1247,260 @@ register({lang}, {filetype}) *vim.treesitter.language.register()*
• {filetype} (`string|string[]`) Filetype(s) to associate with lang
==============================================================================
Lua module: vim.treesitter.languagetree *treesitter-languagetree*
A *LanguageTree* contains a tree of parsers: the root treesitter parser for
{lang} and any "injected" language parsers, which themselves may inject other
languages, recursively. For example a Lua buffer containing some Vimscript
commands needs multiple parsers to fully understand its contents.
To create a LanguageTree (parser object) for a given buffer and language, use: >lua
local parser = vim.treesitter.get_parser(bufnr, lang)
<
(where `bufnr=0` means current buffer). `lang` defaults to 'filetype'. Note:
currently the parser is retained for the lifetime of a buffer but this may
change; a plugin should keep a reference to the parser object if it wants
incremental updates.
Whenever you need to access the current syntax tree, parse the buffer: >lua
local tree = parser:parse({ start_row, end_row })
<
This returns a table of immutable |treesitter-tree| objects representing the
current state of the buffer. When the plugin wants to access the state after a
(possible) edit it must call `parse()` again. If the buffer wasn't edited, the
same tree will be returned again without extra work. If the buffer was parsed
before, incremental parsing will be done of the changed parts.
Note: To use the parser directly inside a |nvim_buf_attach()| Lua callback,
you must call |vim.treesitter.get_parser()| before you register your callback.
But preferably parsing shouldn't be done directly in the change callback
anyway as they will be very frequent. Rather a plugin that does any kind of
analysis on a tree should use a timer to throttle too frequent updates.
LanguageTree:children() *LanguageTree:children()*
Returns a map of language to child tree.
Return: ~
(`table<string,vim.treesitter.LanguageTree>`)
LanguageTree:contains({range}) *LanguageTree:contains()*
Determines whether {range} is contained in the |LanguageTree|.
Parameters: ~
• {range} (`table`) A table with the following fields:
• {[1]} (`integer`) start row
• {[2]} (`integer`) start column
• {[3]} (`integer`) end row
• {[4]} (`integer`) end column
Return: ~
(`boolean`)
LanguageTree:destroy() *LanguageTree:destroy()*
Destroys this |LanguageTree| and all its children.
Any cleanup logic should be performed here.
Note: This DOES NOT remove this tree from a parent. Instead,
`remove_child` must be called on the parent to remove it.
LanguageTree:for_each_tree({fn}) *LanguageTree:for_each_tree()*
Invokes the callback for each |LanguageTree| recursively.
Note: This includes the invoking tree's child trees as well.
Parameters: ~
• {fn} (`fun(tree: TSTree, ltree: vim.treesitter.LanguageTree)`)
LanguageTree:included_regions() *LanguageTree:included_regions()*
Gets the set of included regions managed by this LanguageTree. This can be
different from the regions set by injection query, because a partial
|LanguageTree:parse()| drops the regions outside the requested range. Each
list represents a range in the form of { {start_row}, {start_col},
{start_bytes}, {end_row}, {end_col}, {end_bytes} }.
Return: ~
(`table<integer, Range6[]>`)
LanguageTree:invalidate({reload}) *LanguageTree:invalidate()*
Invalidates this parser and its children.
Should only be called when the tracked state of the LanguageTree is not
valid against the parse tree in treesitter. Doesn't clear filesystem
cache. Called often, so needs to be fast.
Parameters: ~
• {reload} (`boolean?`)
*LanguageTree:is_valid()*
LanguageTree:is_valid({exclude_children}, {range})
Returns whether this LanguageTree is valid, i.e., |LanguageTree:trees()|
reflects the latest state of the source. If invalid, user should call
|LanguageTree:parse()|.
Parameters: ~
• {exclude_children} (`boolean?`) whether to ignore the validity of
children (default `false`)
• {range} (`Range?`) range to check for validity
Return: ~
(`boolean`)
LanguageTree:lang() *LanguageTree:lang()*
Gets the language of this tree node.
Return: ~
(`string`)
*LanguageTree:language_for_range()*
LanguageTree:language_for_range({range})
Gets the appropriate language that contains {range}.
Parameters: ~
• {range} (`table`) A table with the following fields:
• {[1]} (`integer`) start row
• {[2]} (`integer`) start column
• {[3]} (`integer`) end row
• {[4]} (`integer`) end column
Return: ~
(`vim.treesitter.LanguageTree`) tree Managing {range}
*LanguageTree:named_node_for_range()*
LanguageTree:named_node_for_range({range}, {opts})
Gets the smallest named node that contains {range}.
Parameters: ~
• {range} (`table`) A table with the following fields:
• {[1]} (`integer`) start row
• {[2]} (`integer`) start column
• {[3]} (`integer`) end row
• {[4]} (`integer`) end column
• {opts} (`table?`) A table with the following fields:
• {ignore_injections}? (`boolean`, default: `true`) Ignore
injected languages
Return: ~
(`TSNode?`)
*LanguageTree:node_for_range()*
LanguageTree:node_for_range({range}, {opts})
Gets the smallest node that contains {range}.
Parameters: ~
• {range} (`table`) A table with the following fields:
• {[1]} (`integer`) start row
• {[2]} (`integer`) start column
• {[3]} (`integer`) end row
• {[4]} (`integer`) end column
• {opts} (`table?`) A table with the following fields:
• {ignore_injections}? (`boolean`, default: `true`) Ignore
injected languages
Return: ~
(`TSNode?`)
LanguageTree:parent() *LanguageTree:parent()*
Returns the parent tree. `nil` for the root tree.
Return: ~
(`vim.treesitter.LanguageTree?`)
LanguageTree:parse({range}, {on_parse}) *LanguageTree:parse()*
Recursively parse all regions in the language tree using
|treesitter-parsers| for the corresponding languages and run injection
queries on the parsed trees to determine whether child trees should be
created and parsed.
Any region with empty range (`{}`, typically only the root tree) is always
parsed; otherwise (typically injections) only if it intersects {range} (or
if {range} is `true`).
Parameters: ~
• {range} (`boolean|Range?`) Parse this range in the parser's
source. Set to `true` to run a complete parse of the
source (Note: Can be slow!) Set to `false|nil` to only
parse regions with empty ranges (typically only the root
tree without injections).
• {on_parse} (`fun(err?: string, trees?: table<integer, TSTree>)?`)
Function invoked when parsing completes. When provided and
`vim.g._ts_force_sync_parsing` is not set, parsing will
run asynchronously. The first argument to the function is
a string representing the error type, in case of a failure
(currently only possible for timeouts). The second
argument is the list of trees returned by the parse (upon
success), or `nil` if the parse timed out (determined by
'redrawtime').
If parsing was still able to finish synchronously (within
3ms), `parse()` returns the list of trees. Otherwise, it
returns `nil`.
Return: ~
(`table<integer, TSTree>?`)
*LanguageTree:register_cbs()*
LanguageTree:register_cbs({cbs}, {recursive})
Registers callbacks for the |LanguageTree|.
Parameters: ~
• {cbs} (`table<TSCallbackNameOn,function>`) An
|nvim_buf_attach()|-like table argument with the
following handlers:
• `on_bytes` : see |nvim_buf_attach()|.
• `on_changedtree` : a callback that will be called every
time the tree has syntactical changes. It will be
passed two arguments: a table of the ranges (as node
ranges) that changed and the changed tree.
• `on_child_added` : emitted when a child is added to the
tree.
• `on_child_removed` : emitted when a child is removed
from the tree.
• `on_detach` : emitted when the buffer is detached, see
|nvim_buf_detach_event|. Takes one argument, the number
of the buffer.
• {recursive} (`boolean?`) Apply callbacks recursively for all
children. Any new children will also inherit the
callbacks.
LanguageTree:source() *LanguageTree:source()*
Returns the source content of the language tree (bufnr or string).
Return: ~
(`integer|string`)
*LanguageTree:tree_for_range()*
LanguageTree:tree_for_range({range}, {opts})
Gets the tree that contains {range}.
Parameters: ~
• {range} (`table`) A table with the following fields:
• {[1]} (`integer`) start row
• {[2]} (`integer`) start column
• {[3]} (`integer`) end row
• {[4]} (`integer`) end column
• {opts} (`table?`) A table with the following fields:
• {ignore_injections}? (`boolean`, default: `true`) Ignore
injected languages
Return: ~
(`TSTree?`)
LanguageTree:trees() *LanguageTree:trees()*
Returns all trees of the regions parsed by this parser. Does not include
child languages. The result is list-like if
• this LanguageTree is the root, in which case the result is empty or a
singleton list; or
• the root LanguageTree is fully parsed.
Return: ~
(`table<integer, TSTree>`)
==============================================================================
Lua module: vim.treesitter.query *lua-treesitter-query*
@@ -1608,258 +1862,4 @@ TSQuery:disable_pattern({pattern_index}) *TSQuery:disable_pattern()*
• {pattern_index} (`integer`)
==============================================================================
Lua module: vim.treesitter.languagetree *treesitter-languagetree*
A *LanguageTree* contains a tree of parsers: the root treesitter parser for
{lang} and any "injected" language parsers, which themselves may inject other
languages, recursively. For example a Lua buffer containing some Vimscript
commands needs multiple parsers to fully understand its contents.
To create a LanguageTree (parser object) for a given buffer and language, use: >lua
local parser = vim.treesitter.get_parser(bufnr, lang)
<
(where `bufnr=0` means current buffer). `lang` defaults to 'filetype'. Note:
currently the parser is retained for the lifetime of a buffer but this may
change; a plugin should keep a reference to the parser object if it wants
incremental updates.
Whenever you need to access the current syntax tree, parse the buffer: >lua
local tree = parser:parse({ start_row, end_row })
<
This returns a table of immutable |treesitter-tree| objects representing the
current state of the buffer. When the plugin wants to access the state after a
(possible) edit it must call `parse()` again. If the buffer wasn't edited, the
same tree will be returned again without extra work. If the buffer was parsed
before, incremental parsing will be done of the changed parts.
Note: To use the parser directly inside a |nvim_buf_attach()| Lua callback,
you must call |vim.treesitter.get_parser()| before you register your callback.
But preferably parsing shouldn't be done directly in the change callback
anyway as they will be very frequent. Rather a plugin that does any kind of
analysis on a tree should use a timer to throttle too frequent updates.
LanguageTree:children() *LanguageTree:children()*
Returns a map of language to child tree.
Return: ~
(`table<string,vim.treesitter.LanguageTree>`)
LanguageTree:contains({range}) *LanguageTree:contains()*
Determines whether {range} is contained in the |LanguageTree|.
Parameters: ~
• {range} (`table`) A table with the following fields:
• {[1]} (`integer`) start row
• {[2]} (`integer`) start column
• {[3]} (`integer`) end row
• {[4]} (`integer`) end column
Return: ~
(`boolean`)
LanguageTree:destroy() *LanguageTree:destroy()*
Destroys this |LanguageTree| and all its children.
Any cleanup logic should be performed here.
Note: This DOES NOT remove this tree from a parent. Instead,
`remove_child` must be called on the parent to remove it.
LanguageTree:for_each_tree({fn}) *LanguageTree:for_each_tree()*
Invokes the callback for each |LanguageTree| recursively.
Note: This includes the invoking tree's child trees as well.
Parameters: ~
• {fn} (`fun(tree: TSTree, ltree: vim.treesitter.LanguageTree)`)
LanguageTree:included_regions() *LanguageTree:included_regions()*
Gets the set of included regions managed by this LanguageTree. This can be
different from the regions set by injection query, because a partial
|LanguageTree:parse()| drops the regions outside the requested range. Each
list represents a range in the form of { {start_row}, {start_col},
{start_bytes}, {end_row}, {end_col}, {end_bytes} }.
Return: ~
(`table<integer, Range6[]>`)
LanguageTree:invalidate({reload}) *LanguageTree:invalidate()*
Invalidates this parser and its children.
Should only be called when the tracked state of the LanguageTree is not
valid against the parse tree in treesitter. Doesn't clear filesystem
cache. Called often, so needs to be fast.
Parameters: ~
• {reload} (`boolean?`)
*LanguageTree:is_valid()*
LanguageTree:is_valid({exclude_children}, {range})
Returns whether this LanguageTree is valid, i.e., |LanguageTree:trees()|
reflects the latest state of the source. If invalid, user should call
|LanguageTree:parse()|.
Parameters: ~
• {exclude_children} (`boolean?`) whether to ignore the validity of
children (default `false`)
• {range} (`Range?`) range to check for validity
Return: ~
(`boolean`)
LanguageTree:lang() *LanguageTree:lang()*
Gets the language of this tree node.
Return: ~
(`string`)
*LanguageTree:language_for_range()*
LanguageTree:language_for_range({range})
Gets the appropriate language that contains {range}.
Parameters: ~
• {range} (`table`) A table with the following fields:
• {[1]} (`integer`) start row
• {[2]} (`integer`) start column
• {[3]} (`integer`) end row
• {[4]} (`integer`) end column
Return: ~
(`vim.treesitter.LanguageTree`) tree Managing {range}
*LanguageTree:named_node_for_range()*
LanguageTree:named_node_for_range({range}, {opts})
Gets the smallest named node that contains {range}.
Parameters: ~
• {range} (`table`) A table with the following fields:
• {[1]} (`integer`) start row
• {[2]} (`integer`) start column
• {[3]} (`integer`) end row
• {[4]} (`integer`) end column
• {opts} (`table?`) A table with the following fields:
• {ignore_injections}? (`boolean`, default: `true`) Ignore
injected languages
Return: ~
(`TSNode?`)
*LanguageTree:node_for_range()*
LanguageTree:node_for_range({range}, {opts})
Gets the smallest node that contains {range}.
Parameters: ~
• {range} (`table`) A table with the following fields:
• {[1]} (`integer`) start row
• {[2]} (`integer`) start column
• {[3]} (`integer`) end row
• {[4]} (`integer`) end column
• {opts} (`table?`) A table with the following fields:
• {ignore_injections}? (`boolean`, default: `true`) Ignore
injected languages
Return: ~
(`TSNode?`)
LanguageTree:parent() *LanguageTree:parent()*
Returns the parent tree. `nil` for the root tree.
Return: ~
(`vim.treesitter.LanguageTree?`)
LanguageTree:parse({range}, {on_parse}) *LanguageTree:parse()*
Recursively parse all regions in the language tree using
|treesitter-parsers| for the corresponding languages and run injection
queries on the parsed trees to determine whether child trees should be
created and parsed.
Any region with empty range (`{}`, typically only the root tree) is always
parsed; otherwise (typically injections) only if it intersects {range} (or
if {range} is `true`).
Parameters: ~
• {range} (`boolean|Range?`) Parse this range in the parser's
source. Set to `true` to run a complete parse of the
source (Note: Can be slow!) Set to `false|nil` to only
parse regions with empty ranges (typically only the root
tree without injections).
• {on_parse} (`fun(err?: string, trees?: table<integer, TSTree>)?`)
Function invoked when parsing completes. When provided and
`vim.g._ts_force_sync_parsing` is not set, parsing will
run asynchronously. The first argument to the function is
a string representing the error type, in case of a failure
(currently only possible for timeouts). The second
argument is the list of trees returned by the parse (upon
success), or `nil` if the parse timed out (determined by
'redrawtime').
If parsing was still able to finish synchronously (within
3ms), `parse()` returns the list of trees. Otherwise, it
returns `nil`.
Return: ~
(`table<integer, TSTree>?`)
*LanguageTree:register_cbs()*
LanguageTree:register_cbs({cbs}, {recursive})
Registers callbacks for the |LanguageTree|.
Parameters: ~
• {cbs} (`table<TSCallbackNameOn,function>`) An
|nvim_buf_attach()|-like table argument with the
following handlers:
• `on_bytes` : see |nvim_buf_attach()|.
• `on_changedtree` : a callback that will be called every
time the tree has syntactical changes. It will be
passed two arguments: a table of the ranges (as node
ranges) that changed and the changed tree.
• `on_child_added` : emitted when a child is added to the
tree.
• `on_child_removed` : emitted when a child is removed
from the tree.
• `on_detach` : emitted when the buffer is detached, see
|nvim_buf_detach_event|. Takes one argument, the number
of the buffer.
• {recursive} (`boolean?`) Apply callbacks recursively for all
children. Any new children will also inherit the
callbacks.
LanguageTree:source() *LanguageTree:source()*
Returns the source content of the language tree (bufnr or string).
Return: ~
(`integer|string`)
*LanguageTree:tree_for_range()*
LanguageTree:tree_for_range({range}, {opts})
Gets the tree that contains {range}.
Parameters: ~
• {range} (`table`) A table with the following fields:
• {[1]} (`integer`) start row
• {[2]} (`integer`) start column
• {[3]} (`integer`) end row
• {[4]} (`integer`) end column
• {opts} (`table?`) A table with the following fields:
• {ignore_injections}? (`boolean`, default: `true`) Ignore
injected languages
Return: ~
(`TSTree?`)
LanguageTree:trees() *LanguageTree:trees()*
Returns all trees of the regions parsed by this parser. Does not include
child languages. The result is list-like if
• this LanguageTree is the root, in which case the result is empty or a
singleton list; or
• the root LanguageTree is fully parsed.
Return: ~
(`table<integer, TSTree>`)
vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl:

View File

@@ -105,17 +105,20 @@ local config = {
api = {
filename = 'api.txt',
section_order = {
-- Sections at the top, in a specific order:
'vim.c',
'vimscript.c',
'command.c',
'options.c',
'buffer.c',
'extmark.c',
'window.c',
'win_config.c',
'tabpage.c',
-- Sections in alphanumeric order:
'autocmd.c',
'buffer.c',
'command.c',
'extmark.c',
'options.c',
'tabpage.c',
'ui.c',
'win_config.c',
'window.c',
},
fn_name_pat = 'nvim_.*',
files = { 'src/nvim/api' },
@@ -132,66 +135,71 @@ local config = {
lua = {
filename = 'lua.txt',
section_order = {
'hl.lua',
'mpack.lua',
'json.lua',
'base64.lua',
'spell.lua',
-- Sections at the top, in a specific order:
'builtin.lua',
'_options.lua',
'_editor.lua',
'_system.lua',
'_inspector.lua',
'shared.lua',
'loader.lua',
'uri.lua',
'ui.lua',
'_extui.lua',
-- Sections in alphanumeric order:
'base64.lua',
'filetype.lua',
'keymap.lua',
'fs.lua',
'glob.lua',
'hl.lua',
'iter.lua',
'json.lua',
'keymap.lua',
'loader.lua',
'lpeg.lua',
'mpack.lua',
'net.lua',
're.lua',
'regex.lua',
'secure.lua',
'version.lua',
'iter.lua',
'snippet.lua',
'spell.lua',
'_system.lua',
'text.lua',
'ui.lua',
'uri.lua',
'version.lua',
-- Sections at the end, in a specific order:
'tohtml.lua',
'net.lua',
'_extui.lua',
},
files = {
'runtime/lua/vim/iter.lua',
'runtime/lua/tohtml.lua',
'runtime/lua/vim/_editor.lua',
'runtime/lua/vim/_options.lua',
'runtime/lua/vim/shared.lua',
'runtime/lua/vim/loader.lua',
'runtime/lua/vim/uri.lua',
'runtime/lua/vim/ui.lua',
'runtime/lua/vim/_extui.lua',
'runtime/lua/vim/_inspector.lua',
'runtime/lua/vim/_meta/base64.lua',
'runtime/lua/vim/_meta/builtin.lua',
'runtime/lua/vim/_meta/json.lua',
'runtime/lua/vim/_meta/lpeg.lua',
'runtime/lua/vim/_meta/mpack.lua',
'runtime/lua/vim/_meta/re.lua',
'runtime/lua/vim/_meta/regex.lua',
'runtime/lua/vim/_meta/spell.lua',
'runtime/lua/vim/_options.lua',
'runtime/lua/vim/_system.lua',
'runtime/lua/vim/filetype.lua',
'runtime/lua/vim/keymap.lua',
'runtime/lua/vim/fs.lua',
'runtime/lua/vim/glob.lua',
'runtime/lua/vim/hl.lua',
'runtime/lua/vim/iter.lua',
'runtime/lua/vim/keymap.lua',
'runtime/lua/vim/loader.lua',
'runtime/lua/vim/net.lua',
'runtime/lua/vim/secure.lua',
'runtime/lua/vim/version.lua',
'runtime/lua/vim/_inspector.lua',
'runtime/lua/vim/shared.lua',
'runtime/lua/vim/snippet.lua',
'runtime/lua/vim/text.lua',
'runtime/lua/vim/glob.lua',
'runtime/lua/vim/_meta/builtin.lua',
'runtime/lua/vim/_meta/mpack.lua',
'runtime/lua/vim/_meta/json.lua',
'runtime/lua/vim/_meta/base64.lua',
'runtime/lua/vim/_meta/regex.lua',
'runtime/lua/vim/_meta/lpeg.lua',
'runtime/lua/vim/_meta/re.lua',
'runtime/lua/vim/_meta/spell.lua',
'runtime/lua/tohtml.lua',
'runtime/lua/vim/net.lua',
'runtime/lua/vim/ui.lua',
'runtime/lua/vim/uri.lua',
'runtime/lua/vim/version.lua',
},
fn_xform = function(fun)
if contains(fun.module, { 'vim.uri', 'vim.shared', 'vim._editor' }) then
@@ -222,20 +230,6 @@ local config = {
elseif name == 'builtin' then
return 'VIM'
end
if
contains(name, {
'hl',
'mpack',
'json',
'base64',
'spell',
'regex',
'lpeg',
're',
})
then
return 'VIM.' .. name:upper()
end
if name == 'tohtml' then
return 'Lua module: tohtml'
end
@@ -272,22 +266,27 @@ local config = {
lsp = {
filename = 'lsp.txt',
section_order = {
-- Sections at the top, in a specific order:
'lsp.lua',
'client.lua',
-- Sections in alphanumeric order:
'buf.lua',
'diagnostic.lua',
'client.lua',
'codelens.lua',
'completion.lua',
'folding_range.lua',
'inlay_hint.lua',
'tagfunc.lua',
'semantic_tokens.lua',
'diagnostic.lua',
'document_color.lua',
'linked_editing_range.lua',
'folding_range.lua',
'handlers.lua',
'util.lua',
'inlay_hint.lua',
'linked_editing_range.lua',
'log.lua',
'rpc.lua',
'semantic_tokens.lua',
'tagfunc.lua',
-- Sections at the end, in a specific order:
'util.lua',
'protocol.lua',
},
files = {
@@ -329,15 +328,18 @@ local config = {
treesitter = {
filename = 'treesitter.txt',
section_order = {
-- Sections at the top, in a specific order:
'tstree.lua',
'tsnode.lua',
'treesitter.lua',
-- Sections in alphanumeric order:
'dev.lua',
'highlighter.lua',
'language.lua',
'languagetree.lua',
'query.lua',
'tsquery.lua',
'highlighter.lua',
'languagetree.lua',
'dev.lua',
},
append_only = { 'tsquery.lua' },
files = {