Browse Source

doc [ci skip] #11656

tags/nightly
Justin M. Keyes 8 months ago
committed by GitHub
parent
commit
9231684986
No known key found for this signature in database GPG Key ID: 4AEE18F83AFDEB23
14 changed files with 152 additions and 97 deletions
  1. +5
    -4
      CONTRIBUTING.md
  2. +8
    -12
      runtime/doc/api.txt
  3. +28
    -39
      runtime/doc/autocmd.txt
  4. +1
    -0
      runtime/doc/deprecated.txt
  5. +34
    -25
      runtime/doc/eval.txt
  6. +2
    -1
      runtime/doc/help.txt
  7. +1
    -1
      runtime/doc/index.txt
  8. +20
    -4
      runtime/doc/lsp.txt
  9. +20
    -0
      runtime/doc/lua.txt
  10. +3
    -0
      runtime/doc/tabpage.txt
  11. +5
    -5
      runtime/doc/vim_diff.txt
  12. +13
    -1
      runtime/lua/vim/lsp.lua
  13. +10
    -0
      runtime/lua/vim/shared.lua
  14. +2
    -5
      scripts/gen_vimdoc.py

+ 5
- 4
CONTRIBUTING.md View File

@@ -65,10 +65,11 @@ Pull requests (PRs)
Pull requests have three stages: `[WIP]` (Work In Progress), `[RFC]` (Request
For Comment) and `[RDY]` (Ready).

- `[RFC]` is assumed by default, i.e. you are requesting a review.
- Add `[WIP]` to the PR title if you are _not_ requesting feedback and the work
is still in flux.
- Add `[RDY]` if you are _done_ and only waiting on merge.
1. `[RFC]` is assumed by default, **do not** put "RFC" in the PR title (it adds
noise to merge commit messages).
2. Add `[WIP]` to the PR title if you are _not_ requesting feedback and the work
is still in flux.
3. Add `[RDY]` to the PR title if you are _done_ and only waiting on merge.

### Commit messages



+ 8
- 12
runtime/doc/api.txt View File

@@ -183,21 +183,17 @@ External programs (clients) can use the metadata to discover the API, using
any of these approaches:

1. Connect to a running Nvim instance and call |nvim_get_api_info()| via
msgpack-rpc. This is best for clients written in dynamic languages which
msgpack-RPC. This is best for clients written in dynamic languages which
can define functions at runtime.

2. Start Nvim with the |--api-info| option. Useful for clients written in
statically-compiled languages.

3. Use the |api_info()| Vimscript function.

Example: To get a human-readable list of API functions: >
:new|put =map(filter(api_info().functions, '!has_key(v:val,''deprecated_since'')'), 'v:val.name')
<
Example: To get a formatted dump of the API using python (requires the
"pyyaml" and "msgpack-python" modules): >
nvim --api-info | python -c 'import msgpack, sys, yaml; print yaml.dump(msgpack.unpackb(sys.stdin.read()))'
2. Start Nvim with |--api-info|. Useful for statically-compiled clients.
Example (requires Python "pyyaml" and "msgpack-python" modules): >
nvim --api-info | python -c 'import msgpack, sys, yaml; print yaml.dump(msgpack.unpackb(sys.stdin.read()))'
<
3. Use the |api_info()| Vimscript function. >
:lua print(vim.inspect(vim.fn.api_info()))
< Example using |filter()| to exclude non-deprecated API functions: >
:new|put =map(filter(api_info().functions, '!has_key(v:val,''deprecated_since'')'), 'v:val.name')

==============================================================================
API contract *api-contract*


+ 28
- 39
runtime/doc/autocmd.txt View File

@@ -251,7 +251,6 @@ Name triggered by ~

Buffers
|BufAdd| just after adding a buffer to the buffer list
|BufCreate| just after adding a buffer to the buffer list
|BufDelete| before deleting a buffer from the buffer list
|BufWipeout| before completely deleting a buffer

@@ -367,32 +366,29 @@ Name triggered by ~

The alphabetical list of autocommand events: *autocmd-events-abc*

*BufCreate* *BufAdd*
BufAdd or BufCreate Just after creating a new buffer which is
*BufAdd*
BufAdd Just after creating a new buffer which is
added to the buffer list, or adding a buffer
to the buffer list.
Also used just after a buffer in the buffer
list has been renamed.
The BufCreate event is for historic reasons.
NOTE: When this autocommand is executed, the
current buffer "%" may be different from the
buffer being created "<afile>".
to the buffer list, a buffer in the buffer
list was renamed.
Before |BufEnter|.
NOTE: Current buffer "%" may be different from
the buffer being created "<afile>".
*BufDelete*
BufDelete Before deleting a buffer from the buffer list.
The BufUnload may be called first (if the
buffer was loaded).
Also used just before a buffer in the buffer
list is renamed.
NOTE: When this autocommand is executed, the
current buffer "%" may be different from the
buffer being deleted "<afile>" and "<abuf>".
Don't change to another buffer, it will cause
problems.
NOTE: Current buffer "%" may be different from
the buffer being deleted "<afile>" and "<abuf>".
Do not change to another buffer.
*BufEnter*
BufEnter After entering a buffer. Useful for setting
options for a file type. Also executed when
starting to edit a buffer, after the
BufReadPost autocommands.
After |BufAdd|.
After |BufReadPost|.
*BufFilePost*
BufFilePost After changing the name of the current buffer
with the ":file" or ":saveas" command.
@@ -405,9 +401,8 @@ BufHidden Just before a buffer becomes hidden. That is,
the buffer, but the buffer is not unloaded or
deleted. Not used for ":qa" or ":q" when
exiting Vim.
NOTE: When this autocommand is executed, the
current buffer "%" may be different from the
buffer being unloaded "<afile>".
NOTE: current buffer "%" may be different from
the buffer being unloaded "<afile>".
*BufLeave*
BufLeave Before leaving to another buffer. Also when
leaving or closing the current window and the
@@ -418,9 +413,8 @@ BufNew Just after creating a new buffer. Also used
just after a buffer has been renamed. When
the buffer is added to the buffer list BufAdd
will be triggered too.
NOTE: When this autocommand is executed, the
current buffer "%" may be different from the
buffer being created "<afile>".
NOTE: Current buffer "%" may be different from
the buffer being created "<afile>".
*BufNewFile*
BufNewFile When starting to edit a file that doesn't
exist. Can be used to read in a skeleton
@@ -451,13 +445,11 @@ BufUnload Before unloading a buffer. This is when the
may be after a BufWritePost and before a
BufDelete. Also used for all buffers that are
loaded when Vim is going to exit.
NOTE: When this autocommand is executed, the
current buffer "%" may be different from the
buffer being unloaded "<afile>".
Don't change to another buffer or window, it
will cause problems!
When exiting and v:dying is 2 or more this
event is not triggered.
NOTE: Current buffer "%" may be different from
the buffer being unloaded "<afile>".
Do not change to another buffer or window!
Not triggered when exiting and v:dying is 2 or
more.
*BufWinEnter*
BufWinEnter After a buffer is displayed in a window. This
can be when the buffer is loaded (after
@@ -476,11 +468,10 @@ BufWinLeave Before a buffer is removed from a window.
Not when it's still visible in another window.
Also triggered when exiting. It's triggered
before BufUnload or BufHidden.
NOTE: When this autocommand is executed, the
current buffer "%" may be different from the
buffer being unloaded "<afile>".
When exiting and v:dying is 2 or more this
event is not triggered.
NOTE: Current buffer "%" may be different from
the buffer being unloaded "<afile>".
Not triggered when exiting and v:dying is 2 or
more.
*BufWipeout*
BufWipeout Before completely deleting a buffer. The
BufUnload and BufDelete events may be called
@@ -488,11 +479,9 @@ BufWipeout Before completely deleting a buffer. The
buffer list). Also used just before a buffer
is renamed (also when it's not in the buffer
list).
NOTE: When this autocommand is executed, the
current buffer "%" may be different from the
buffer being deleted "<afile>".
Don't change to another buffer, it will cause
problems.
NOTE: Current buffer "%" may be different from
the buffer being deleted "<afile>".
Do not change to another buffer.
*BufWrite* *BufWritePre*
BufWrite or BufWritePre Before writing the whole buffer to a file.
*BufWriteCmd*


+ 1
- 0
runtime/doc/deprecated.txt View File

@@ -28,6 +28,7 @@ Environment Variables ~
$NVIM_LISTEN_ADDRESS is ignored.

Events ~
*BufCreate* Use |BufAdd| instead.
*EncodingChanged* Never fired; 'encoding' is always "utf-8".
*FileEncoding* Never fired; equivalent to |EncodingChanged|.
*GUIEnter* Never fired; use |UIEnter| instead.


+ 34
- 25
runtime/doc/eval.txt View File

@@ -2520,6 +2520,9 @@ and({expr}, {expr}) *and()*
api_info() *api_info()*
Returns Dictionary of |api-metadata|.

View it in a nice human-readable format: >
:lua print(vim.inspect(vim.fn.api_info()))

append({lnum}, {text}) *append()*
When {text} is a |List|: Append each item of the |List| as a
text line below line {lnum} in the current buffer.
@@ -5453,35 +5456,41 @@ jobstart({cmd}[, {opts}]) *jobstart()*

*jobstart-options*
{opts} is a dictionary with these keys:
|on_stdout|: stdout event handler (function name or |Funcref|)
stdout_buffered : read stdout in |channel-buffered| mode.
|on_stderr|: stderr event handler (function name or |Funcref|)
stderr_buffered : read stderr in |channel-buffered| mode.
|on_exit| : exit event handler (function name or |Funcref|)
cwd : Working directory of the job; defaults to
|current-directory|.
env : A dict of strings to append (or replace see
|clear_env|) to the current environment.
clear_env: If set, use the exact values passed in |env|
rpc : If set, |msgpack-rpc| will be used to communicate
with the job over stdin and stdout. "on_stdout" is
then ignored, but "on_stderr" can still be used.
pty : If set, the job will be connected to a new pseudo
terminal and the job streams are connected to the
master file descriptor. "on_stderr" is ignored,
"on_stdout" receives all output.

width : (pty only) Width of the terminal screen
height : (pty only) Height of the terminal screen
TERM : (pty only) $TERM environment variable
detach : (non-pty only) Detach the job process: it will
not be killed when Nvim exits. If the process
exits before Nvim, "on_exit" will be invoked.
clear_env: (boolean) `env` defines the job environment
exactly, instead of merging current environment.
cwd: (string, default=|current-directory|) Working
directory of the job.
detach: (boolean) Detach the job process: it will not be
killed when Nvim exits. If the process exits
before Nvim, `on_exit` will be invoked.
env: (dict) Map of environment variable name:value
pairs extending (or replacing if |clear_env|)
the current environment.
height: (number) Height of the `pty` terminal.
|on_exit|: (function) Callback invoked when the job exits.
|on_stdout|: (function) Callback invoked when the job emits
stdout data.
|on_stderr|: (function) Callback invoked when the job emits
stderr data.
pty: (boolean) Connect the job to a new pseudo
terminal, and its streams to the master file
descriptor. Then `on_stderr` is ignored,
`on_stdout` receives all output.
rpc: (boolean) Use |msgpack-rpc| to communicate with
the job over stdio. Then `on_stdout` is ignored,
but `on_stderr` can still be used.
stderr_buffered: (boolean) Collect data until EOF (stream closed)
before invoking `on_stderr`. |channel-buffered|
stdout_buffered: (boolean) Collect data until EOF (stream
closed) before invoking `on_stdout`. |channel-buffered|
TERM: (string) Sets the `pty` $TERM environment variable.
width: (number) Width of the `pty` terminal.

{opts} is passed as |self| dictionary to the callback; the
caller may set other keys to pass application-specific data.

Returns:
- The channel ID on success
- |channel-id| on success
- 0 on invalid arguments
- -1 if {cmd}[0] is not executable.
See also |job-control|, |channel|, |msgpack-rpc|.


+ 2
- 1
runtime/doc/help.txt View File

@@ -137,6 +137,7 @@ Special issues ~

Programming language support ~
|indent.txt| automatic indenting for C and other languages
|lsp.txt| Language Server Protocol (LSP)
|syntax.txt| syntax highlighting
|filetype.txt| settings done specifically for a type of file
|quickfix.txt| commands for a quick edit-compile-fix cycle
@@ -169,7 +170,7 @@ Versions ~
Standard plugins ~
|pi_gzip.txt| Reading and writing compressed files
|pi_health.txt| Healthcheck framework
|pi_matchit.txt| Extended "%" matching
|pi_matchit.txt| Extended |%| matching
|pi_msgpack.txt| msgpack utilities
|pi_netrw.txt| Reading and writing files over a network
|pi_paren.txt| Highlight matching parens


+ 1
- 1
runtime/doc/index.txt View File

@@ -10,7 +10,7 @@ short description. The lists are sorted on ASCII value.
Tip: When looking for certain functionality, use a search command. E.g.,
to look for deleting something, use: "/delete".

For an overview of options see help.txt |option-list|.
For an overview of options see |option-list|.
For an overview of built-in functions see |functions|.
For a list of Vim variables see |vim-variable|.
For a complete listing of all help items see |help-tags|.


+ 20
- 4
runtime/doc/lsp.txt View File

@@ -49,9 +49,9 @@ go-to-definition, hover, etc. Example config: >
nnoremap <silent> 1gD <cmd>lua vim.lsp.buf.type_definition()<CR>
nnoremap <silent> gr <cmd>lua vim.lsp.buf.references()<CR>

Nvim provides the vim.lsp.omnifunc 'omnifunc' handler which allows
|i_CTRL-X_CTRL-O| to consume LSP completion features. Example config (note the
use of |v:lua| to call Lua from Vimscript): >
Nvim provides the |vim.lsp.omnifunc| 'omnifunc' handler which allows
|i_CTRL-X_CTRL-O| to consume LSP completion. Example config (note the use of
|v:lua| to call Lua from Vimscript): >

" Use LSP omni-completion in Python files.
autocmd Filetype python setlocal omnifunc=v:lua.vim.lsp.omnifunc
@@ -477,7 +477,23 @@ notify({...}) *vim.lsp.notify()*
TODO: Documentation

omnifunc({findstart}, {base}) *vim.lsp.omnifunc()*
TODO: Documentation
Implements 'omnifunc' compatible LSP completion.

Parameters: ~
{findstart} 0 or 1, decides behavior
{base} If findstart=0, text to match against

Return: ~
(number) Decided by`findstart`:
• findstart=0: column where the completion starts, or -2
or -3
• findstart=1: list of matches (actually just calls
|complete()|)

See also: ~
|complete-functions|
|complete-items|
|CompleteDone|

on_error({code}, {err}) *vim.lsp.on_error()*
TODO: Documentation


+ 20
- 0
runtime/doc/lua.txt View File

@@ -885,6 +885,16 @@ deepcopy({orig}) *vim.deepcopy()*
Return: ~
New table of copied keys and (nested) values.

endswith({s}, {suffix}) *vim.endswith()*
Tests if `s` ends with `suffix` .

Parameters: ~
{s} (string) a string
{suffix} (string) a suffix

Return: ~
(boolean) true if `suffix` is a suffix of s

gsplit({s}, {sep}, {plain}) *vim.gsplit()*
Splits a string at each instance of a separator.

@@ -962,6 +972,16 @@ split({s}, {sep}, {plain}) *vim.split()*
See also: ~
|vim.gsplit()|

startswith({s}, {prefix}) *vim.startswith()*
Tests if `s` starts with `prefix` .

Parameters: ~
{s} (string) a string
{prefix} (string) a prefix

Return: ~
(boolean) true if `prefix` is a prefix of s

tbl_add_reverse_lookup({o}) *vim.tbl_add_reverse_lookup()*
Add the reverse lookup values to an existing table. For
example: `tbl_add_reverse_lookup { A = 1 } == { [1] = 'A', A =


+ 3
- 0
runtime/doc/tabpage.txt View File

@@ -190,6 +190,9 @@ gt *i_CTRL-<PageDown>* *i_<C-PageDown>*
{count}<C-PageDown>
{count}gt Go to tab page {count}. The first tab page has number one.

CTRL-<Tab> *CTRL-<Tab>*
CTRL-W g<Tab> *g<Tab>* *CTRL-W_g<Tab>*
g<Tab> Go to previous (last accessed) tab page.

:tabp[revious] *:tabp* *:tabprevious* *gT* *:tabN*
:tabN[ext] *:tabNext* *CTRL-<PageUp>*


+ 5
- 5
runtime/doc/vim_diff.txt View File

@@ -270,11 +270,6 @@ are always available and may be used simultaneously. See |provider-python|.
|json_encode()| behaviour slightly changed: now |msgpack-special-dict| values
are accepted, but |v:none| is not.

*v:none* variable is absent. In Vim it represents “no value” in “js” strings
like "[,]" parsed as "[v:none]" by |js_decode()|.

*js_encode()* and *js_decode()* functions are also absent.

Viminfo text files were replaced with binary (messagepack) ShaDa files.
Additional differences:

@@ -443,6 +438,11 @@ Compile-time features:
Emacs tags support
X11 integration (see |x11-selection|)

Eval:
*js_encode()*
*js_decode()*
*v:none* (used by Vim to represent JavaScript "undefined"); use |v:null| instead.

Highlight groups:
*hl-StatusLineTerm* *hl-StatusLineTermNC* are unnecessary because Nvim
supports 'winhighlight' window-local highlights.


+ 13
- 1
runtime/lua/vim/lsp.lua View File

@@ -914,7 +914,18 @@ function lsp.buf_notify(bufnr, method, params)
end)
end

--- Implements 'omnifunc' compatible LSP completion.
---
--@see |complete-functions|
--@see |complete-items|
--@see |CompleteDone|
---
--@param findstart 0 or 1, decides behavior
--@param base If findstart=0, text to match against
---
--@return (number) Decided by `findstart`:
--- - findstart=0: column where the completion starts, or -2 or -3
--- - findstart=1: list of matches (actually just calls |complete()|)
function lsp.omnifunc(findstart, base)
local _ = log.debug() and log.debug("omnifunc.findstart", { findstart = findstart, base = base })

@@ -936,7 +947,7 @@ function lsp.omnifunc(findstart, base)
local line_to_cursor = line:sub(1, pos[2])
local _ = log.trace() and log.trace("omnifunc.line", pos, line)

-- Get the start postion of the current keyword
-- Get the start position of the current keyword
local textMatch = vim.fn.match(line_to_cursor, '\\k*$')
local params = util.make_position_params()



+ 10
- 0
runtime/lua/vim/shared.lua View File

@@ -331,21 +331,21 @@ function vim.pesc(s)
return s:gsub('[%(%)%.%%%+%-%*%?%[%]%^%$]', '%%%1')
end

--- Tests if `s` starts with `prefix`.
---
--@param s (string) a string
--@param prefix (string) a prefix
--@return (boolean) true if `prefix` is a prefix of s
function vim.startswith(s, prefix)
vim.validate { s = {s, 's'}; prefix = {prefix, 's'}; }
return s:sub(1, #prefix) == prefix
end

--- Tests if `s` ends with `suffix`.
---
--@param s (string) a string
--@param suffix (string) a suffix
--@return (boolean) true if `suffix` is a suffix of s
function vim.endswith(s, suffix)
vim.validate { s = {s, 's'}; suffix = {suffix, 's'}; }
return #suffix == 0 or s:sub(-#suffix) == suffix


+ 2
- 5
scripts/gen_vimdoc.py View File

@@ -167,10 +167,7 @@ CONFIG = {
# HACK. TODO(justinmk): class/structure support in lua2dox
if 'lsp.client' == f'{fstem}.{name}'
else f'*vim.lsp.{fstem}.{name}()*')),
'module_override': {
# Combine are exposed on the `vim` module.
'shared': 'vim',
},
'module_override': {},
'append_only': [],
},
}
@@ -821,7 +818,7 @@ def main(config):
stdin=subprocess.PIPE,
# silence warnings
# runtime/lua/vim/lsp.lua:209: warning: argument 'foo' not found
stderr=subprocess.DEVNULL)
stderr=(subprocess.STDOUT if DEBUG else subprocess.DEVNULL))
p.communicate(
config.format(
input=CONFIG[target]['files'],


Loading…
Cancel
Save