diff options
47 files changed, 2018 insertions, 1454 deletions
diff --git a/runtime/doc/deprecated.txt b/runtime/doc/deprecated.txt index 1b16a19aca..9ca4e66c7b 100644 --- a/runtime/doc/deprecated.txt +++ b/runtime/doc/deprecated.txt @@ -141,7 +141,7 @@ LSP FUNCTIONS - *vim.lsp.buf.range_formatting()* Use |vim.lsp.formatexpr()| or |vim.lsp.buf.format()| instead. - *vim.lsp.util.get_progress_messages()* Use |vim.lsp.status()| or access - `progress` of |vim.lsp.client| + `progress` of |vim.lsp.Client| - *vim.lsp.get_active_clients()* Use |vim.lsp.get_clients()| - *vim.lsp.for_each_buffer_client()* Use |vim.lsp.get_clients()| - *vim.lsp.util.lookup_section()* Use |vim.tbl_get()| and diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt index 28f43a70e0..1d566efec8 100644 --- a/runtime/doc/develop.txt +++ b/runtime/doc/develop.txt @@ -179,6 +179,8 @@ Strict "vimdoc" subset: - Do not use indentation in random places—that prevents the page from using "flow" layout. If you need a preformatted section, put it in a |help-codeblock| starting with ">". +- Parameters and fields are documented as `{foo}`. +- Optional parameters and fields are documented as `{foo}?`. C docstrings ~ @@ -189,9 +191,8 @@ from the docstrings defined in src/nvim/api/*.c. Docstring format: - Lines start with `///` - Special tokens start with `@` followed by the token name: - `@note`, `@param`, `@returns` -- Limited markdown is supported. - - List-items start with `-` (useful to nest or "indent") + `@note`, `@param`, `@return` +- Markdown is supported. - Use ``` for code samples. Code samples can be annotated as `vim` or `lua` @@ -233,11 +234,33 @@ definitions. The |lua-vim| :help is generated from the docstrings. Docstring format: - Use LuaCATS annotations: https://luals.github.io/wiki/annotations/ -- Limited markdown is supported. - - List-items start with `-` (useful to nest or "indent") +- Markdown is supported. - Use ``` for code samples. Code samples can be annotated as `vim` or `lua` - Use `@nodoc` to prevent documentation generation. +- Use `@inlinedoc` to inline `@class` blocks into `@param` blocks. + E.g. >lua + --- Object with fields: + --- @class myOpts + --- @inlinedoc + --- + --- Documentation for some field + --- @field somefield? integer + + --- @param opts? myOpts + function foo(opts) + end +< + + Will be rendered as: >vimdoc + + foo({opts}) + + Parameters: + - {opts}? (table) Object with the fields: + - {somefield}? (integer) Documentation + for some field +< - Files which has `@meta` are only used for typing and documentation. Example: the help for |vim.paste()| is generated from a docstring decorating diff --git a/runtime/doc/diagnostic.txt b/runtime/doc/diagnostic.txt index dbfa0148af..29859f7b05 100644 --- a/runtime/doc/diagnostic.txt +++ b/runtime/doc/diagnostic.txt @@ -38,24 +38,6 @@ optionally supplied). A good rule of thumb is that if a method is meant to modify the diagnostics for a buffer (e.g. |vim.diagnostic.set()|) then it requires a namespace. - *diagnostic-structure* -A diagnostic is a Lua table with the following keys. Required keys are -indicated with (+): - - bufnr: Buffer number - lnum(+): The starting line of the diagnostic - end_lnum: The final line of the diagnostic - col(+): The starting column of the diagnostic - end_col: The final column of the diagnostic - severity: The severity of the diagnostic |vim.diagnostic.severity| - message(+): The diagnostic text - source: The source of the diagnostic - code: The diagnostic code - user_data: Arbitrary data plugins or users can add - -Diagnostics use the same indexing as the rest of the Nvim API (i.e. 0-based -rows and columns). |api-indexing| - *vim.diagnostic.severity* *diagnostic-severity* The "severity" key in a diagnostic is one of the values defined in `vim.diagnostic.severity`: @@ -361,6 +343,105 @@ Example: >lua ============================================================================== Lua module: vim.diagnostic *diagnostic-api* +*vim.Diagnostic* + *diagnostic-structure* + + Diagnostics use the same indexing as the rest of the Nvim API (i.e. + 0-based rows and columns). |api-indexing| + + Fields: ~ + • {bufnr}? (`integer`) Buffer number + • {lnum} (`integer`) The starting line of the diagnostic + (0-indexed) + • {end_lnum}? (`integer`) The final line of the diagnostic (0-indexed) + • {col} (`integer`) The starting column of the diagnostic + (0-indexed) + • {end_col}? (`integer`) The final column of the diagnostic + (0-indexed) + • {severity}? (`vim.diagnostic.Severity`) The severity of the + diagnostic |vim.diagnostic.severity| + • {message} (`string`) The diagnostic text + • {source}? (`string`) The source of the diagnostic + • {code}? (`string|integer`) The diagnostic code + • {_tags}? (`{ deprecated: boolean, unnecessary: boolean}`) + • {user_data}? (`any`) arbitrary data plugins can add + • {namespace}? (`integer`) + +*vim.diagnostic.NS* + + Fields: ~ + • {name} (`string`) + • {opts} (`vim.diagnostic.Opts`) + • {user_data} (`table`) + • {disabled}? (`boolean`) + +*vim.diagnostic.Opts* + + Fields: ~ + • {float}? (`boolean|vim.diagnostic.Opts.Float`) + • {update_in_insert}? (`boolean`) + • {underline}? (`boolean|vim.diagnostic.Opts.Underline`) + • {virtual_text}? (`boolean|vim.diagnostic.Opts.VirtualText`) + • {signs}? (`boolean|vim.diagnostic.Opts.Signs`) + • {severity_sort}? (`boolean|{reverse?:boolean}`) + +*vim.diagnostic.Opts.Float* + + Fields: ~ + • {bufnr}? (`integer`) + • {namespace}? (`integer`) + • {scope}? (`'line'|'buffer'|'cursor'|'c'|'l'|'b'`) + • {pos}? (`integer|{[1]:integer,[2]:integer}`) + • {severity_sort}? (`boolean|{reverse?:boolean}`) + • {severity}? (`vim.diagnostic.SeverityFilter`) + • {header}? (`string|{[1]:string,[2]:any}`) + • {source}? (`boolean|string`) + • {format}? (`fun(diagnostic:vim.Diagnostic): string`) + • {prefix}? (`string|table`) + • {suffix}? (`string|table`) + • {focus_id}? (`string`) + +*vim.diagnostic.Opts.Signs* + + Fields: ~ + • {severity}? (`vim.diagnostic.SeverityFilter`) + • {priority}? (`integer`) + • {text}? (`table<vim.diagnostic.Severity,string>`) + • {numhl}? (`table<vim.diagnostic.Severity,string>`) + • {linehl}? (`table<vim.diagnostic.Severity,string>`) + • {texthl}? (`table<vim.diagnostic.Severity,string>`) + +*vim.diagnostic.Opts.Underline* + + Fields: ~ + • {severity}? (`vim.diagnostic.SeverityFilter`) + +*vim.diagnostic.Opts.VirtualText* + + Fields: ~ + • {severity}? (`vim.diagnostic.SeverityFilter`) + • {source}? (`boolean|string`) + • {prefix}? (`string|function`) + • {suffix}? (`string|function`) + • {spacing}? (`integer`) + • {format}? (`function`) + • {hl_mode}? (`'replace'|'combine'|'blend'`) + • {virt_text}? (`{[1]:string,[2]:any}[]`) + • {virt_text_pos}? (`'eol'|'overlay'|'right_align'|'inline'`) + • {virt_text_win_col}? (`integer`) + • {virt_text_hide}? (`boolean`) + +*vim.diagnostic.OptsResolved* + + Fields: ~ + • {float} (`vim.diagnostic.Opts.Float`) + • {update_in_insert} (`boolean`) + • {underline} (`vim.diagnostic.Opts.Underline`) + • {virtual_text} (`vim.diagnostic.Opts.VirtualText`) + • {signs} (`vim.diagnostic.Opts.Signs`) + • {severity_sort} (`{reverse?:boolean}`) + + config({opts}, {namespace}) *vim.diagnostic.config()* Configure diagnostic options globally or for a specific diagnostic namespace. @@ -518,7 +599,8 @@ fromqflist({list}) *vim.diagnostic.fromqflist()* |getloclist()|. Return: ~ - (`vim.Diagnostic[]`) array of |diagnostic-structure| + (`vim.Diagnostic[]`) array of |diagnostic-structure|. See + |vim.Diagnostic|. get({bufnr}, {opts}) *vim.diagnostic.get()* Get current diagnostics. @@ -538,7 +620,7 @@ get({bufnr}, {opts}) *vim.diagnostic.get()* Return: ~ (`vim.Diagnostic[]`) table A list of diagnostic items |diagnostic-structure|. Keys `bufnr`, `end_lnum`, `end_col`, and - `severity` are guaranteed to be present. + `severity` are guaranteed to be present. See |vim.Diagnostic|. get_namespace({namespace}) *vim.diagnostic.get_namespace()* Get namespace metadata. @@ -563,7 +645,7 @@ get_next({opts}) *vim.diagnostic.get_next()* • {opts} (`table?`) See |vim.diagnostic.goto_next()| Return: ~ - (`vim.Diagnostic?`) Next diagnostic + (`vim.Diagnostic?`) Next diagnostic. See |vim.Diagnostic|. get_next_pos({opts}) *vim.diagnostic.get_next_pos()* Return the position of the next diagnostic in the current buffer. @@ -582,7 +664,7 @@ get_prev({opts}) *vim.diagnostic.get_prev()* • {opts} (`table?`) See |vim.diagnostic.goto_next()| Return: ~ - (`vim.Diagnostic?`) Previous diagnostic + (`vim.Diagnostic?`) Previous diagnostic. See |vim.Diagnostic|. get_prev_pos({opts}) *vim.diagnostic.get_prev_pos()* Return the position of the previous diagnostic in the current buffer. @@ -599,21 +681,22 @@ goto_next({opts}) *vim.diagnostic.goto_next()* Parameters: ~ • {opts} (`table?`) Configuration table with the following keys: - • namespace: (integer) Only consider diagnostics from the + • {namespace} (`integer`) Only consider diagnostics from the given namespace. - • cursor_position: (cursor position) Cursor position as a - (row, col) tuple. See |nvim_win_get_cursor()|. Defaults to - the current cursor position. - • wrap: (boolean, default true) Whether to loop around file or - not. Similar to 'wrapscan'. - • severity: See |diagnostic-severity|. - • float: (boolean or table, default true) If "true", call - |vim.diagnostic.open_float()| after moving. If a table, pass - the table as the {opts} parameter to - |vim.diagnostic.open_float()|. Unless overridden, the float - will show diagnostics at the new cursor position (as if - "cursor" were passed to the "scope" option). - • win_id: (number, default 0) Window ID + • {cursor_position}? (`{[1]:integer,[2]:integer}`) Cursor + position as a (row, col) tuple. See |nvim_win_get_cursor()|. + Defaults to the current cursor position. + • {wrap}? (`boolean`, default: `true`) Whether to loop around + file or not. Similar to 'wrapscan'. + • {severity} (`vim.diagnostic.Severity`) See + |diagnostic-severity|. + • {float}? (`boolean|vim.diagnostic.Opts.Float`, default: + `true`) If "true", call |vim.diagnostic.open_float()| after + moving. If a table, pass the table as the {opts} parameter + to |vim.diagnostic.open_float()|. Unless overridden, the + float will show diagnostics at the new cursor position (as + if "cursor" were passed to the "scope" option). + • {win_id}? (`integer`, default: `0`) Window ID goto_prev({opts}) *vim.diagnostic.goto_prev()* Move to the previous diagnostic in the current buffer. @@ -678,7 +761,7 @@ match({str}, {pat}, {groups}, {severity_map}, {defaults}) Return: ~ (`vim.Diagnostic?`) |diagnostic-structure| or `nil` if {pat} fails to - match {str}. + match {str}. See |vim.Diagnostic|. open_float({opts}) *vim.diagnostic.open_float()* Show diagnostics in a floating window. @@ -758,7 +841,7 @@ set({namespace}, {bufnr}, {diagnostics}, {opts}) *vim.diagnostic.set()* • {namespace} (`integer`) The diagnostic namespace • {bufnr} (`integer`) Buffer number • {diagnostics} (`vim.Diagnostic[]`) A list of diagnostic items - |diagnostic-structure| + |diagnostic-structure|. See |vim.Diagnostic|. • {opts} (`table?`) Display options to pass to |vim.diagnostic.show()| @@ -767,28 +850,30 @@ setloclist({opts}) *vim.diagnostic.setloclist()* Parameters: ~ • {opts} (`table?`) Configuration table with the following keys: - • namespace: (number) Only add diagnostics from the given + • {namespace}? (`integer`) Only add diagnostics from the given namespace. - • winnr: (number, default 0) Window number to set location - list for. - • open: (boolean, default true) Open the location list after - setting. - • title: (string) Title of the location list. Defaults to + • {winnr}? (`integer`, default: `0`) Window number to set + location list for. + • {open}? (`boolean`, default: `true`) Open the location list + after setting. + • {title}? (`string`) Title of the location list. Defaults to "Diagnostics". - • severity: See |diagnostic-severity|. + • {severity}? (`vim.diagnostic.Severity`) See + |diagnostic-severity|. setqflist({opts}) *vim.diagnostic.setqflist()* Add all diagnostics to the quickfix list. Parameters: ~ • {opts} (`table?`) Configuration table with the following keys: - • namespace: (number) Only add diagnostics from the given + • {namespace}? (`integer`) Only add diagnostics from the given namespace. - • open: (boolean, default true) Open quickfix list after - setting. - • title: (string) Title of quickfix list. Defaults to + • {open}? (`boolean`, default: `true`) Open quickfix list + after setting. + • {title}? (`string`) Title of quickfix list. Defaults to "Diagnostics". - • severity: See |diagnostic-severity|. + • {severity}? (`vim.diagnostic.Severity`) See + |diagnostic-severity|. *vim.diagnostic.show()* show({namespace}, {bufnr}, {diagnostics}, {opts}) @@ -804,7 +889,7 @@ show({namespace}, {bufnr}, {diagnostics}, {opts}) namespace and buffer. This can be used to display a list of diagnostics without saving them or to display only a subset of diagnostics. May not be used when - {namespace} or {bufnr} is nil. + {namespace} or {bufnr} is nil. See |vim.Diagnostic|. • {opts} (`table?`) Display options. See |vim.diagnostic.config()|. @@ -814,7 +899,7 @@ toqflist({diagnostics}) *vim.diagnostic.toqflist()* Parameters: ~ • {diagnostics} (`vim.Diagnostic[]`) List of diagnostics - |diagnostic-structure|. + |diagnostic-structure|. See |vim.Diagnostic|. Return: ~ (`table[]`) of quickfix list items |setqflist-what| diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt index c14c0e5b9c..d78189780d 100644 --- a/runtime/doc/lsp.txt +++ b/runtime/doc/lsp.txt @@ -218,7 +218,7 @@ Each response handler has this signature: > - {ctx} (table) Table of calling state associated with the handler, with these keys: - {method} (string) |lsp-method| name. - - {client_id} (number) |vim.lsp.client| identifier. + - {client_id} (number) |vim.lsp.Client| identifier. - {bufnr} (Buffer) Buffer handle. - {params} (table|nil) Request parameters table. - {version} (number) Document version at time of @@ -366,31 +366,6 @@ https://microsoft.github.io/language-server-protocol/specifications/specificatio LSP notification shape: https://microsoft.github.io/language-server-protocol/specifications/specification-current/#notificationMessage - *lsp-on-list-handler* - -`on_list` receives a table with: - - - `items` table[], structured like |setqflist-what| - - `title` string, title for the list. - - `context` table|nil. `ctx` from |lsp-handler| - -This table can be used with vim.fn.setqflist or vim.fn.setloclist. E.g.: ->lua - local function on_list(options) - vim.fn.setqflist({}, ' ', options) - vim.api.nvim_command('cfirst') - end - - vim.lsp.buf.definition{on_list=on_list} - vim.lsp.buf.references(nil, {on_list=on_list}) -< -If you prefer loclist do something like this: ->lua - local function on_list(options) - vim.fn.setloclist(0, {}, ' ', options) - vim.api.nvim_command('lopen') - end -< ================================================================================ LSP HIGHLIGHT *lsp-highlight* @@ -557,7 +532,7 @@ LspNotify *LspNotify* LspProgress *LspProgress* Upon receipt of a progress notification from the server. Notifications can - be polled from a `progress` ring buffer of a |vim.lsp.client| or use + be polled from a `progress` ring buffer of a |vim.lsp.Client| or use |vim.lsp.status()| to get an aggregate message If the server sends a "work done progress", the `pattern` is set to `kind` @@ -583,7 +558,7 @@ LspRequest *LspRequest* will trigger with {type} == `cancel`. When used from Lua, the client ID, request ID, and request are sent in - the "data" table. See {requests} in |vim.lsp.client| for details on the + the "data" table. See {requests} in |vim.lsp.Client| for details on the {request} value. If the request type is `complete`, the request will be deleted from the client's pending requests table immediately after calling the event's callbacks. Example: >lua @@ -712,77 +687,6 @@ buf_request_sync({bufnr}, {method}, {params}, {timeout_ms}) (`string?`) err On timeout, cancel, or error, `err` is a string describing the failure reason, and `result` is nil. -client *vim.lsp.client* - LSP client object. You can get an active client object via - |vim.lsp.get_client_by_id()| or |vim.lsp.get_clients()|. - • Methods: - • request(method, params, [handler], bufnr) Sends a request to the - server. This is a thin wrapper around {client.rpc.request} with some - additional checking. If {handler} is not specified, If one is not - found there, then an error will occur. Returns: {status}, - {[client_id]}. {status} is a boolean indicating if the notification - was successful. If it is `false`, then it will always be `false` (the - client has shutdown). If {status} is `true`, the function returns - {request_id} as the second result. You can use this with - `client.cancel_request(request_id)` to cancel the request. - • request_sync(method, params, timeout_ms, bufnr) Sends a request to the - server and synchronously waits for the response. This is a wrapper - around {client.request} Returns: { err=err, result=result }, a - dictionary, where `err` and `result` come from the |lsp-handler|. On - timeout, cancel or error, returns `(nil, err)` where `err` is a string - describing the failure reason. If the request was unsuccessful returns - `nil`. - • notify(method, params) Sends a notification to an LSP server. Returns: - a boolean to indicate if the notification was successful. If it is - false, then it will always be false (the client has shutdown). - • cancel_request(id) Cancels a request with a given request id. Returns: - same as `notify()`. - • stop([force]) Stops a client, optionally with force. By default, it - will just ask the server to shutdown without force. If you request to - stop a client which has previously been requested to shutdown, it will - automatically escalate and force shutdown. - • is_stopped() Checks whether a client is stopped. Returns: true if the - client is fully stopped. - • on_attach(client, bufnr) Runs the on_attach function from the client's - config if it was defined. Useful for buffer-local setup. - • supports_method(method, [opts]): boolean Checks if a client supports a - given method. Always returns true for unknown off-spec methods. [opts] - is a optional `{bufnr?: integer}` table. Some language server - capabilities can be file specific. - • Members - • {id} (number): The id allocated to the client. - • {name} (string): If a name is specified on creation, that will be - used. Otherwise it is just the client id. This is used for logs and - messages. - • {rpc} (table): RPC client object, for low level interaction with the - client. See |vim.lsp.rpc.start()|. - • {offset_encoding} (string): The encoding used for communicating with - the server. You can modify this in the `config`'s `on_init` method - before text is sent to the server. - • {handlers} (table): The handlers used by the client as described in - |lsp-handler|. - • {commands} (table): Table of command name to function which is called - if any LSP action (code action, code lenses, ...) triggers the - command. Client commands take precedence over the global command - registry. - • {requests} (table): The current pending requests in flight to the - server. Entries are key-value pairs with the key being the request ID - while the value is a table with `type`, `bufnr`, and `method` - key-value pairs. `type` is either "pending" for an active request, or - "cancel" for a cancel request. It will be "complete" ephemerally while - executing |LspRequest| autocmds when replies are received from the - server. - • {config} (table): Reference of the table that was passed by the user - to |vim.lsp.start_client()|. - • {server_capabilities} (table): Response from the server sent on - `initialize` describing the server's capabilities. - • {progress} A ring buffer (|vim.ringbuf()|) containing progress - messages sent by the server. - • {settings} Map with language server specific settings. See {config} in - |vim.lsp.start_client()| - • {flags} A table with flags for the client. See {config} in - |vim.lsp.start_client()| - client_is_stopped({client_id}) *vim.lsp.client_is_stopped()* Checks whether a client is stopped. @@ -820,10 +724,9 @@ formatexpr({opts}) *vim.lsp.formatexpr()* 'v:lua.vim.lsp.formatexpr(#{timeout_ms:250})'`. Parameters: ~ - • {opts} (`table`) options for customizing the formatting expression - which takes the following optional keys: - • timeout_ms (default 500ms). The timeout period for the - formatting request. + • {opts} (`table?`) A table with the following fields: + • {timeout_ms} (`integer`, default: 500ms) The timeout period + for the formatting request.. *vim.lsp.get_buffers_by_client_id()* get_buffers_by_client_id({client_id}) @@ -843,23 +746,23 @@ get_client_by_id({client_id}) *vim.lsp.get_client_by_id()* • {client_id} (`integer`) client id Return: ~ - (`lsp.Client?`) client rpc object + (`vim.lsp.Client?`) client rpc object get_clients({filter}) *vim.lsp.get_clients()* Get active clients. Parameters: ~ - • {filter} (`table?`) A table with key-value pairs used to filter the - returned clients. The available keys are: - • id (number): Only return clients with the given id - • bufnr (number): Only return clients attached to this + • {filter} (`table?`) Key-value pairs used to filter the returned + clients. + • {id}? (`integer`) Only return clients with the given id + • {bufnr}? (`integer`) Only return clients attached to this buffer - • name (string): Only return clients with the given name - • method (string): Only return clients supporting the given - method + • {name}? (`string`) Only return clients with the given name + • {method}? (`string`) Only return clients supporting the + given method Return: ~ - (`lsp.Client[]`) List of |vim.lsp.client| objects + (`vim.lsp.Client[]`) List of |vim.lsp.Client| objects get_log_path() *vim.lsp.get_log_path()* Gets the path of the logfile used by the LSP client. @@ -937,15 +840,16 @@ start({config}, {opts}) *vim.lsp.start()* `ftplugin/<filetype_name>.lua` (See |ftplugin-name|) Parameters: ~ - • {config} (`lsp.ClientConfig`) Same configuration as documented in - |vim.lsp.start_client()| - • {opts} (`lsp.StartOpts?`) Optional keyword arguments: - • reuse_client (fun(client: client, config: table): boolean) - |