kevin/neovim
1
Fork 0
mirror of https://github.com/neovim/neovim.git synced 2024-12-24 05:05:00 -07:00
Code Issues Packages Projects Releases Wiki Activity

docs: misc

Browse Source 
Co-authored-by: Kevin Pham <keevan.pham@gmail.com>
This commit is contained in:
Justin M. Keyes 2023-07-12 19:27:14 +02:00
parent 214b125132
commit d2f8133024
15 changed files with 124 additions and 111 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
CONTRIBUTING.md
View File

@ -304,14 +304,10 @@ Lua documentation uses a subset of [EmmyLua] annotations. See [:help dev-doc-lua
---@return type {description}
```
- If possible, add type information (`table`, `string`, `number`, ...). Multiple valid types are separated by a bar (`string|table`). Indicate optional parameters via `type|nil`.
- If a function in your Lua module should _not_ be documented (e.g. internal or local function), set the doc comment to:
```
---@private
```
- Mark deprecated functions with:
```
---@deprecated
```
- If a function in your Lua module should _not_ be documented, add `@nodoc`.
- If the function is internal or otherwise non-public add `@private`.
- Private functions usually should be underscore-prefixed (named "_foo", not "foo").
- Mark deprecated functions with `@deprecated`.
Reviewing
---------

45
MAINTAIN.md
View File

@ -131,41 +131,46 @@ We may maintain forks, if we are waiting on upstream changes: https://github.com
Non-technical dependencies
--------------------------
* GitHub users:
* https://github.com/marvim
* https://github.com/nvim-winget
* Domain names (held in https://namecheap.com):
* neovim.org
* neovim.io
* packspec.org
* pkgjson.org
* DNS for the above domains is managed in https://cloudflare.com (not the domain registrar)
Automation (CI)
---------------
Our CI and automation jobs are primarily driven by GitHub Actions. Guidelines:
### Backup
### General
Discussions from issues and PRs are backed up here:
https://github.com/neovim/neovim-backup
### Development guidelines
* CI and automation jobs are primarily driven by GitHub Actions.
* Avoid macOS if an Ubuntu or a Windows runner can be used instead. This is
because macOS runners have [tighter restrictions on the number of concurrent
jobs](https://docs.github.com/en/actions/learn-github-actions/usage-limits-billing-and-administration#usage-limits).
### Runner versions
* For special-purpose jobs where the runner version doesn't really matter,
prefer `-latest` tags so we don't need to manually bump the versions. An
example of a special-purpose workflow is `labeler.yml`.
* For our testing jobs, which are in `test.yml` and `build.yml`, prefer to use
the latest stable (i.e. non-beta) version explicitly. Avoid using the
`-latest` tags here as it makes it difficult to determine from an unrelated
PR if a failure is due to the PR itself or due to GitHub bumping the
`-latest` tag without our knowledge. There's also a high risk that automatic
bumping the CI versions will fail due to manual work being required from
experience.
* For our release job, which is `release.yml`, prefer to use the oldest stable
(i.e. non-deprecated) versions available. The reason is that we're trying to
produce images that work in the broadest number of environments, and
therefore want to use older releases.
* Runner versions:
* For special-purpose jobs where the runner version doesn't really matter,
prefer `-latest` tags so we don't need to manually bump the versions. An
example of a special-purpose workflow is `labeler.yml`.
* For our testing jobs, which are in `test.yml` and `build.yml`, prefer to
use the latest stable (i.e. non-beta) version explicitly. Avoid using the
`-latest` tags here as it makes it difficult to determine from an
unrelated PR if a failure is due to the PR itself or due to GitHub bumping
the `-latest` tag without our knowledge. There's also a high risk that
automatically bumping the CI versions will fail due to manual work being
required from experience.
* For our release job, which is `release.yml`, prefer to use the oldest
stable (i.e. non-deprecated) versions available. The reason is that we're
trying to produce images that work in the broadest number of environments,
and therefore want to use older releases.
See also
--------

19
runtime/doc/api.txt
View File

@ -1849,6 +1849,9 @@ nvim_get_commands({*opts}) *nvim_get_commands()*
Return: ~
Map of maps describing commands.
See also: ~
• |nvim_get_all_options_info()|
nvim_parse_cmd({str}, {opts}) *nvim_parse_cmd()*
Parse command line.
@ -1933,6 +1936,9 @@ nvim_get_all_options_info() *nvim_get_all_options_info()*
Return: ~
dictionary of all options
See also: ~
• |nvim_get_commands()|
nvim_get_option_info2({name}, {*opts}) *nvim_get_option_info2()*
Gets the option information for one option from arbitrary buffer or window
@ -3238,8 +3244,8 @@ nvim_tabpage_set_var({tabpage}, {name}, {value})
Autocmd Functions *api-autocmd*
nvim_clear_autocmds({*opts}) *nvim_clear_autocmds()*
Clear all autocommands that match the corresponding {opts}. To delete a
particular autocmd, see |nvim_del_autocmd()|.
Clears all autocommands selected by {opts}. To delete autocmds see
|nvim_del_autocmd()|.
Parameters: ~
• {opts} Parameters
@ -3381,15 +3387,10 @@ nvim_del_augroup_by_name({name}) *nvim_del_augroup_by_name()*
• |autocmd-groups|
nvim_del_autocmd({id}) *nvim_del_autocmd()*
Delete an autocommand by id.
NOTE: Only autocommands created via the API have an id.
Deletes an autocommand by id.
Parameters: ~
• {id} Integer The id returned by nvim_create_autocmd
See also: ~
• |nvim_create_autocmd()|
• {id} Integer Autocommand id returned by |nvim_create_autocmd()|
nvim_exec_autocmds({event}, {*opts}) *nvim_exec_autocmds()*
Execute all autocommands for {event} that match the corresponding {opts}

2
runtime/doc/develop.txt
View File

@ -132,7 +132,7 @@ DOCUMENTATION *dev-doc*
optimize for the reader's time and energy: be "precise yet concise".
- Prefer the active voice: "Foo does X", not "X is done by Foo".
- "The words you choose are an essential part of the user experience."
https://developer.apple.com/design/human-interface-guidelines/foundations/writing/
https://developer.apple.com/design/human-interface-guidelines/writing
- "...without being overly colloquial or frivolous."
https://developers.google.com/style/tone
- Write docstrings (as opposed to inline comments) with present tense ("Gets"),

44
runtime/doc/lua.txt
View File

@ -70,6 +70,17 @@ https://www.lua.org/doc/cacm2018.pdf
- Stackful coroutines enable cooperative multithreading, generators, and
versatile control for both Lua and its host (Nvim).
*iterator*
An iterator is just a function that can be called repeatedly to get the "next"
value of a collection (or any other |iterable|). This interface is expected by
|for-in| loops, produced by |pairs()|, supported by |vim.iter|, etc.
https://www.lua.org/pil/7.1.html
*iterable*
An "iterable" is anything that |vim.iter()| can consume: tables, dicts, lists,
iterator functions, tables implementing the |__call()| metamethod, and
|vim.iter()| objects.
*lua-call-function*
Lua functions can be called in multiple ways. Consider the function: >lua
local foo = function(a, b)
@ -1909,7 +1920,8 @@ vim.endswith({s}, {suffix}) *vim.endswith()*
(boolean) `true` if `suffix` is a suffix of `s`
vim.gsplit({s}, {sep}, {opts}) *vim.gsplit()*
Splits a string at each instance of a separator.
Gets an |iterator| that splits a string at each instance of a separator,
in "lazy" fashion (as opposed to |vim.split()| which is "eager").
Example: >lua
@ -2065,16 +2077,17 @@ vim.spairs({t}) *vim.spairs()*
Enumerate a table sorted by its keys.
Parameters: ~
• {t} (table) List-like table
• {t} (table) Dict-like table
Return: ~
iterator over sorted keys and their values
_ iterator over sorted keys and their values
See also: ~
• Based on https://github.com/premake/premake-core/blob/master/src/base/table.lua
vim.split({s}, {sep}, {opts}) *vim.split()*
Splits a string at each instance of a separator.
Splits a string at each instance of a separator and returns the result as
a table (unlike |vim.gsplit()|).
Examples: >lua
@ -3192,22 +3205,19 @@ vim.version.range({spec}) *vim.version.range()*
Lua module: vim.iter *vim.iter*
This module provides a generic interface for working with iterables:
tables, lists, iterator functions, pair()/ipair()-like iterators, and
`vim.iter()` objects.
*vim.iter()* wraps its table or function argument into an *Iter* object
with methods (such as |Iter:filter()| and |Iter:map()|) that transform the
underlying source data. These methods can be chained together to create
iterator "pipelines". Each pipeline stage receives as input the output
values from the prior stage. The values used in the first stage of the
pipeline depend on the type passed to this function:
*vim.iter()* is an interface for |iterable|s: it wraps a table or function
argument into an *Iter* object with methods (such as |Iter:filter()| and
|Iter:map()|) that transform the underlying source data. These methods can
be chained together to create iterator "pipelines". Each pipeline stage
receives as input the output values from the prior stage. The values used
in the first stage of the pipeline depend on the type passed to this
function:
• List tables pass only the value of each element
• Non-list tables pass both the key and value of each element
• Function iterators pass all of the values returned by their respective
• Non-list (dict) tables pass both the key and value of each element
• Function |iterator|s pass all of the values returned by their respective
function
• Tables with a metatable implementing __call are treated as function
• Tables with a metatable implementing |__call()| are treated as function
iterators
Examples: >lua

30
runtime/doc/luaref.txt
View File

@ -437,7 +437,7 @@ middle of a block, then an explicit inner block can be used, as in the idioms
the last statements in their (inner) blocks.
------------------------------------------------------------------------------
2.4.5 For Statement *luaref-for* *luaref-langForStat*
2.4.5 For Statement *for* *luaref-langForStat*
The `for` statement has two forms: one numeric and one generic.
@ -477,8 +477,8 @@ Note the following:
after the `for` ends or is broken. If you need this value, assign it to
another variable before breaking or exiting the loop.
*luaref-in*
The generic `for` statement works over functions, called iterators. On each
*for-in*
The generic `for` statement works over functions, called |iterator|s. On each
iteration, the iterator function is called to produce a new value, stopping
when this new value is `nil`. The generic `for` loop has the following syntax:
>
@ -3611,8 +3611,8 @@ getmetatable({object}) *luaref-getmetatable()*
associated value. Otherwise, returns the metatable of the given
object.
ipairs({t}) *luaref-ipairs()*
Returns three values: an iterator function, the table {t}, and 0, so
ipairs({t}) *ipairs()*
Returns three values: an |iterator| function, the table {t}, and 0, so
that the construction
`for i,v in ipairs(t) do` `body` `end`
@ -3645,7 +3645,7 @@ loadstring({string} [, {chunkname}]) *luaref-loadstring()*
assert(loadstring(s))()
<
next({table} [, {index}]) *luaref-next()*
next({table} [, {index}]) *next()*
Allows a program to traverse all fields of a table. Its first argument
is a table and its second argument is an index in this table. `next`
returns the next index of the table and its associated value. When
@ -3657,15 +3657,15 @@ next({table} [, {index}]) *luaref-next()*
The order in which the indices are enumerated is not specified, `even
for` `numeric indices`. (To traverse a table in numeric order, use a
numerical `for` or the `ipairs` |luaref-ipairs()| function.)
numerical `for` or the |ipairs()| function.)
The behavior of `next` is `undefined` if, during the traversal, you
assign any value to a non-existent field in the table. You may however
modify existing fields. In particular, you may clear existing fields.
pairs({t}) *luaref-pairs()*
Returns three values: the `next` |luaref-next()| function, the table
{t}, and `nil`, so that the construction
pairs({t}) *pairs()*
Returns three values: the |next()| function, the table {t}, and `nil`,
so that the construction
`for k,v in pairs(t) do` `body` `end`
@ -3826,7 +3826,7 @@ coroutine.wrap({f}) *coroutine.wrap()*
coroutine.yield({...}) *coroutine.yield()*
Suspends the execution of the calling coroutine. The coroutine cannot
be running a C function, a metamethod, or an iterator. Any arguments
be running a C function, a metamethod, or an |iterator|. Any arguments
to `yield` are passed as extra results to `resume`.
==============================================================================
@ -4036,7 +4036,7 @@ string.format({formatstring}, {...}) *string.format()*
This function does not accept string values containing embedded zeros.
string.gmatch({s}, {pattern}) *string.gmatch()*
Returns an iterator function that, each time it is called, returns the
Returns an |iterator| function that, each time it is called, returns the
next captures from {pattern} over string {s}.
If {pattern} specifies no captures, then the whole match is produced
@ -4271,7 +4271,7 @@ table.foreach({table}, {f}) *table.foreach()*
returns a non-`nil` value, then the loop is broken, and this value is
returned as the final value of `table.foreach`.
See |luaref-next()| for extra information about table traversals.
See |next()| for extra information about table traversals.
table.foreachi({table}, {f}) *table.foreachi()*
Executes the given {f} over the numerical indices of {table}. For each
@ -4464,7 +4464,7 @@ io.input([{file}]) *io.input()*
an error code.
io.lines([{filename}]) *io.lines()*
Opens the given file name in read mode and returns an iterator
Opens the given file name in read mode and returns an |iterator|
function that, each time it is called, returns a new line from the
file. Therefore, the construction
@ -4533,7 +4533,7 @@ file:flush() *luaref-file:flush()*
Saves any written data to `file`.
file:lines() *luaref-file:lines()*
Returns an iterator function that, each time it is called, returns a
Returns an |iterator| function that, each time it is called, returns a
new line from the file. Therefore, the construction
`for line in file:lines() do` `body` `end`

2
runtime/doc/news.txt
View File

@ -71,7 +71,7 @@ The following new APIs and features were added.
https://github.com/neovim/neovim/pull/23611
• |vim.iter()| provides a generic iterator interface for tables and Lua
iterators |luaref-in|.
iterators |for-in|.
• Added |vim.ringbuf()| to create ring buffers.

3
runtime/doc/various.txt
View File

@ -495,6 +495,9 @@ user command or autocommand, the script in which it was defined is reported.
< - When 'keywordprg' is equal to "man -s", a [count]
before "K" is inserted after the "-s". If there is
no count, the "-s" is removed.
*K-lsp-default*
- The Nvim |LSP| client sets K to show LSP "hover"
feature. |lsp-defaults|
*v_K*
{Visual}K Like "K", but use the visually highlighted text for

22
runtime/doc/vim_diff.txt
View File

@ -115,13 +115,15 @@ DEFAULT MAPPINGS
Nvim creates the following default mappings at |startup|. You can disable any
of these in your config by simply removing the mapping, e.g. ":unmap Y".
- |Y-default|
- |i_CTRL-U-default|
- |i_CTRL-W-default|
- |CTRL-L-default|
- |&-default|
- |v_#-default|
- |v_star-default|
- Y |Y-default|
- <C-U> |i_CTRL-U-default|
- <C-W> |i_CTRL-W-default|
- <C-L> |CTRL-L-default|
- & |&-default|
- # |v_#-default|
- * |v_star-default|
- Nvim LSP client defaults |lsp-defaults|
- K |K-lsp-default|
DEFAULT AUTOCOMMANDS
*default-autocmds*
@ -511,6 +513,9 @@ Mappings:
Motion:
The |jumplist| avoids useless/phantom jumps.
Performance:
Folds are not updated during insert-mode.
Syntax highlighting:
syncolor.vim has been removed. Nvim now sets up default highlighting groups
automatically for both light and dark backgrounds, regardless of whether or
@ -732,9 +737,6 @@ Options:
*'ttytype'* *'tty'*
weirdinvert
Performance:
Folds are not updated during insert-mode.
Plugins:
- logiPat

9
runtime/lua/vim/_meta/api.lua generated
View File

@ -691,8 +691,8 @@ function vim.api.nvim_call_function(fn, args) end
--- @param data string data to write. 8-bit clean: can contain NUL bytes.
function vim.api.nvim_chan_send(chan, data) end
--- Clear all autocommands that match the corresponding {opts}. To delete a
--- particular autocmd, see `nvim_del_autocmd()`.
--- Clears all autocommands selected by {opts}. To delete autocmds see
--- `nvim_del_autocmd()`.
---
--- @param opts vim.api.keyset.clear_autocmds Parameters
--- • event: (string|table) Examples:
@ -919,10 +919,9 @@ function vim.api.nvim_del_augroup_by_id(id) end
--- @param name string String The name of the group.
function vim.api.nvim_del_augroup_by_name(name) end
--- Delete an autocommand by id.
--- NOTE: Only autocommands created via the API have an id.
--- Deletes an autocommand by id.
---
--- @param id integer Integer The id returned by nvim_create_autocmd
--- @param id integer Integer Autocommand id returned by `nvim_create_autocmd()`
function vim.api.nvim_del_autocmd(id) end
--- Deletes the current line.

23
runtime/lua/vim/iter.lua
View File

@ -1,22 +1,15 @@
---@defgroup vim.iter
---
--- This module provides a generic interface for working with
--- iterables: tables, lists, iterator functions, pair()/ipair()-like iterators,
--- and \`vim.iter()\` objects.
---
--- \*vim.iter()\* wraps its table or function argument into an \*Iter\* object
--- with methods (such as |Iter:filter()| and |Iter:map()|) that transform the
--- underlying source data. These methods can be chained together to create
--- iterator "pipelines". Each pipeline stage receives as input the output
--- values from the prior stage. The values used in the first stage of the
--- pipeline depend on the type passed to this function:
--- \*vim.iter()\* is an interface for |iterable|s: it wraps a table or function argument into an
--- \*Iter\* object with methods (such as |Iter:filter()| and |Iter:map()|) that transform the
--- underlying source data. These methods can be chained together to create iterator "pipelines".
--- Each pipeline stage receives as input the output values from the prior stage. The values used in
--- the first stage of the pipeline depend on the type passed to this function:
---
--- - List tables pass only the value of each element
--- - Non-list tables pass both the key and value of each element
--- - Function iterators pass all of the values returned by their respective
--- function
--- - Tables with a metatable implementing __call are treated as function
--- iterators
--- - Non-list (dict) tables pass both the key and value of each element
--- - Function |iterator|s pass all of the values returned by their respective function
--- - Tables with a metatable implementing |__call()| are treated as function iterators
---
--- Examples:
--- <pre>lua

10
runtime/lua/vim/shared.lua
View File

@ -60,7 +60,8 @@ function vim.deepcopy(orig)
return deepcopy(orig)
end
--- Splits a string at each instance of a separator.
--- Gets an |iterator| that splits a string at each instance of a separator, in "lazy" fashion
--- (as opposed to |vim.split()| which is "eager").
---
--- Example:
--- <pre>lua
@ -159,7 +160,8 @@ function vim.gsplit(s, sep, opts)
end
end
--- Splits a string at each instance of a separator.
--- Splits a string at each instance of a separator and returns the result as a table (unlike
--- |vim.gsplit()|).
---
--- Examples:
--- <pre>lua
@ -530,8 +532,8 @@ end
---
---@see Based on https://github.com/premake/premake-core/blob/master/src/base/table.lua
---
---@param t table List-like table
---@return iterator over sorted keys and their values
---@param t table Dict-like table
---@return # iterator over sorted keys and their values
function vim.spairs(t)
assert(type(t) == 'table', string.format('Expected table, got %s', type(t)))

10
src/nvim/api/autocmd.c
View File

@ -517,11 +517,9 @@ cleanup:
return autocmd_id;
}
/// Delete an autocommand by id.
/// Deletes an autocommand by id.
///
/// NOTE: Only autocommands created via the API have an id.
/// @param id Integer The id returned by nvim_create_autocmd
/// @see |nvim_create_autocmd()|
/// @param id Integer Autocommand id returned by |nvim_create_autocmd()|
void nvim_del_autocmd(Integer id, Error *err)
FUNC_API_SINCE(9)
{
@ -533,8 +531,8 @@ void nvim_del_autocmd(Integer id, Error *err)
}
}
/// Clear all autocommands that match the corresponding {opts}. To delete
/// a particular autocmd, see |nvim_del_autocmd()|.
/// Clears all autocommands selected by {opts}. To delete autocmds see |nvim_del_autocmd()|.
///
/// @param opts Parameters
/// - event: (string|table)
/// Examples:

2
src/nvim/api/command.c
View File

@ -1230,6 +1230,8 @@ err:
///
/// Currently only |user-commands| are supported, not builtin Ex commands.
///
/// @see |nvim_get_all_options_info()|
///
/// @param opts Optional parameters. Currently only supports
/// {"builtin":false}
/// @param[out] err Error details, if any.

2
src/nvim/api/options.c
View File

@ -315,6 +315,8 @@ void nvim_set_option_value(uint64_t channel_id, String name, Object value, Dict(
/// The dictionary has the full option names as keys and option metadata
/// dictionaries as detailed at |nvim_get_option_info2()|.
///
/// @see |nvim_get_commands()|
///
/// @return dictionary of all options
Dictionary nvim_get_all_options_info(Error *err)
FUNC_API_SINCE(7)