From 7b529e7912517af078e005dd7b06b3d042be9cb7 Mon Sep 17 00:00:00 2001 From: TJ DeVries Date: Thu, 2 Jul 2020 07:09:17 -0400 Subject: [PATCH] doc: fix scripts and regenerate (#12506) * Fix some small doc issues * doc: fixup * doc: fixup * Fix lint and rebase * Remove bad advice * Ugh, stupid mpack files... * Don't let people include these for now until they specifically want to * Prevent duplicate tag --- .gitignore | 2 + runtime/doc/api.txt | 105 ++++++++----- runtime/doc/lsp.txt | 279 ++++++++++++++++++++++++----------- runtime/doc/lua.txt | 75 ++++++++-- runtime/lua/vim/lsp.lua | 10 +- runtime/lua/vim/lsp/buf.lua | 13 ++ runtime/lua/vim/lsp/rpc.lua | 6 +- runtime/lua/vim/lsp/util.lua | 39 ++++- runtime/lua/vim/shared.lua | 20 +-- scripts/gen_vimdoc.py | 66 ++++++++- scripts/lua2dox_filter | 11 +- src/nvim/api/buffer.c | 2 + src/nvim/lua/vim.lua | 2 + 13 files changed, 474 insertions(+), 156 deletions(-) diff --git a/.gitignore b/.gitignore index f4037c718a..699d493b59 100644 --- a/.gitignore +++ b/.gitignore @@ -61,6 +61,8 @@ local.mk /runtime/doc/*.html /runtime/doc/tags.ref /runtime/doc/errors.log +# Don't include the mpack files. +/runtime/doc/*.mpack # CLion /.idea/ diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index 67260904a6..ea3a8242ae 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -475,6 +475,9 @@ created for extmark changes. ============================================================================== Global Functions *api-global* +nvim__get_lib_dir() *nvim__get_lib_dir()* + TODO: Documentation + nvim__id({obj}) *nvim__id()* Returns object given as argument. @@ -526,7 +529,8 @@ nvim__id_float({flt}) *nvim__id_float()* nvim__inspect_cell({grid}, {row}, {col}) *nvim__inspect_cell()* TODO: Documentation -nvim__put_attr({id}, {c0}, {c1}) *nvim__put_attr()* + *nvim__put_attr()* +nvim__put_attr({id}, {start_row}, {start_col}, {end_row}, {end_col}) Set attrs in nvim__buf_set_lua_hl callbacks TODO(bfredl): This is rather pedestrian. The final interface @@ -612,7 +616,8 @@ nvim_create_buf({listed}, {scratch}) *nvim_create_buf()* Parameters: ~ {listed} Sets 'buflisted' {scratch} Creates a "throwaway" |scratch-buffer| for - temporary work (always 'nomodified') + temporary work (always 'nomodified'). Also sets + 'nomodeline' on the buffer. Return: ~ Buffer handle, or 0 on error @@ -938,6 +943,23 @@ nvim_get_proc_children({pid}) *nvim_get_proc_children()* Return: ~ Array of child process ids, empty if process not found. +nvim_get_runtime_file({name}, {all}) *nvim_get_runtime_file()* + Find files in runtime directories + + 'name' can contain wildcards. For example + nvim_get_runtime_file("colors/*.vim", true) will return all + color scheme files. + + It is not an error to not find any files. An empty array is + returned then. + + Parameters: ~ + {name} pattern of files to search for + {all} whether to return all matches or only the first + + Return: ~ + list of absolute paths to the found files + nvim_get_var({name}) *nvim_get_var()* Gets a global (g:) variable. @@ -1526,6 +1548,9 @@ nvim_unsubscribe({event}) *nvim_unsubscribe()* ============================================================================== Buffer Functions *api-buffer* + +For more information on buffers, see |buffers|. + Unloaded Buffers:~ Buffers may be unloaded by the |:bunload| command or the @@ -1539,6 +1564,12 @@ affected. You can use |nvim_buf_is_loaded()| or |nvim_buf_line_count()| to check whether a buffer is loaded. + *nvim__buf_add_decoration()* +nvim__buf_add_decoration({buffer}, {ns_id}, {hl_group}, {start_row}, + {start_col}, {end_row}, {end_col}, + {virt_text}) + TODO: Documentation + *nvim__buf_redraw_range()* nvim__buf_redraw_range({buffer}, {first}, {last}) TODO: Documentation @@ -1559,7 +1590,7 @@ nvim__buf_stats({buffer}) *nvim__buf_stats()* TODO: Documentation *nvim_buf_add_highlight()* -nvim_buf_add_highlight({buffer}, {ns_id}, {hl_group}, {line}, +nvim_buf_add_highlight({buffer}, {src_id}, {hl_group}, {line}, {col_start}, {col_end}) Adds a highlight to buffer. @@ -1756,8 +1787,8 @@ nvim_buf_get_extmarks({buffer}, {ns_id}, {start}, {end}, {opts}) as (0,0) and (-1,-1) respectively, thus the following are equivalent: > - nvim_buf_get_extmarks(0, my_ns, 0, -1, {}) - nvim_buf_get_extmarks(0, my_ns, [0,0], [-1,-1], {}) + nvim_buf_get_extmarks(0, my_ns, 0, -1, {}) + nvim_buf_get_extmarks(0, my_ns, [0,0], [-1,-1], {}) < If `end` is less than `start` , traversal works backwards. @@ -1766,18 +1797,18 @@ nvim_buf_get_extmarks({buffer}, {ns_id}, {start}, {end}, {opts}) Example: > - local a = vim.api - local pos = a.nvim_win_get_cursor(0) - local ns = a.nvim_create_namespace('my-plugin') - -- Create new extmark at line 1, column 1. - local m1 = a.nvim_buf_set_extmark(0, ns, 0, 0, 0, {}) - -- Create new extmark at line 3, column 1. - local m2 = a.nvim_buf_set_extmark(0, ns, 0, 2, 0, {}) - -- Get extmarks only from line 3. - local ms = a.nvim_buf_get_extmarks(0, ns, {2,0}, {2,0}, {}) - -- Get all marks in this buffer + namespace. - local all = a.nvim_buf_get_extmarks(0, ns, 0, -1, {}) - print(vim.inspect(ms)) + local a = vim.api + local pos = a.nvim_win_get_cursor(0) + local ns = a.nvim_create_namespace('my-plugin') + -- Create new extmark at line 1, column 1. + local m1 = a.nvim_buf_set_extmark(0, ns, 0, 0, 0, {}) + -- Create new extmark at line 3, column 1. + local m2 = a.nvim_buf_set_extmark(0, ns, 0, 2, 0, {}) + -- Get extmarks only from line 3. + local ms = a.nvim_buf_get_extmarks(0, ns, {2,0}, {2,0}, {}) + -- Get all marks in this buffer + namespace. + local all = a.nvim_buf_get_extmarks(0, ns, 0, -1, {}) + print(vim.inspect(ms)) < Parameters: ~ @@ -1888,7 +1919,7 @@ nvim_buf_get_var({buffer}, {name}) *nvim_buf_get_var()* Variable value *nvim_buf_get_virtual_text()* -nvim_buf_get_virtual_text({buffer}, {lnum}) +nvim_buf_get_virtual_text({buffer}, {line}) Get the virtual text (annotation) for a buffer line. The virtual text is returned as list of lists, whereas the @@ -2022,7 +2053,8 @@ nvim_buf_set_var({buffer}, {name}, {value}) *nvim_buf_set_var()* {value} Variable value *nvim_buf_set_virtual_text()* -nvim_buf_set_virtual_text({buffer}, {ns_id}, {line}, {chunks}, {opts}) +nvim_buf_set_virtual_text({buffer}, {src_id}, {line}, {chunks}, + {opts}) Set the virtual text (annotation) for a buffer line. By default (and currently the only option) the text will be @@ -2346,6 +2378,25 @@ nvim_ui_detach() *nvim_ui_detach()* Removes the client from the list of UIs. |nvim_list_uis()| + *nvim_ui_pum_set_bounds()* +nvim_ui_pum_set_bounds({width}, {height}, {row}, {col}) + Tells Nvim the geometry of the popumenu, to align floating + windows with an external popup menu. + + Note that this method is not to be confused with + |nvim_ui_pum_set_height()|, which sets the number of visible + items in the popup menu, while this function sets the bounding + box of the popup menu, including visual decorations such as + boarders and sliders. Floats need not use the same font size, + nor be anchored to exact grid corners, so one can set + floating-point numbers to the popup menu geometry. + + Parameters: ~ + {width} Popupmenu width. + {height} Popupmenu height. + {row} Popupmenu row. + {col} Popupmenu height. + nvim_ui_pum_set_height({height}) *nvim_ui_pum_set_height()* Tells Nvim the number of elements displaying in the popumenu, to decide and movement. @@ -2353,22 +2404,6 @@ nvim_ui_pum_set_height({height}) *nvim_ui_pum_set_height()* Parameters: ~ {height} Popupmenu height, must be greater than zero. - *nvim_ui_pum_set_bounds()* -nvim_ui_pum_set_bounds({width}, {height}, {row}, {col}) - - Tells Nvim the geometry of the popumenu, to align floating - windows with an external popup menu. Note that this method - is not to be confused with |nvim_ui_pum_set_height()|, which - sets the number of visible items in the popup menu, while - this function sets the bounding box of the popup menu, - including visual decorations such as boarders and sliders. - - Parameters: ~ - {width} Popupmenu width. - {height} Popupmenu height. - {row} Popupmenu row. - {height} Popupmenu height. - nvim_ui_set_option({name}, {value}) *nvim_ui_set_option()* TODO: Documentation diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt index c3d25586b6..15587955de 100644 --- a/runtime/doc/lsp.txt +++ b/runtime/doc/lsp.txt @@ -364,13 +364,12 @@ buf_is_attached({bufnr}, {client_id}) *vim.lsp.buf_is_attached()* {client_id} (number) the client id buf_notify({bufnr}, {method}, {params}) *vim.lsp.buf_notify()* - Sends a notification to all servers attached to the buffer. + Send a notification to a server Parameters: ~ - {bufnr} (optional, number) Buffer handle, or 0 for - current - {method} (string) LSP method name - {params} (string) Parameters to send to the server + {bufnr} [number] (optional): The number of the buffer + {method} [string]: Name of the request method + {params} [string]: Arguments to send to the server Return: ~ true if any client returns true; false otherwise @@ -470,6 +469,10 @@ client() *vim.lsp.client* response from the server in `server_capabilities` . client_is_stopped({client_id}) *vim.lsp.client_is_stopped()* + TODO: Documentation + + *vim.lsp.define_default_sign()* +define_default_sign({name}, {properties}) TODO: Documentation err_message({...}) *vim.lsp.err_message()* @@ -547,7 +550,7 @@ once({fn}) *vim.lsp.once()* optional_validator({fn}) *vim.lsp.optional_validator()* TODO: Documentation -request({method}, {params}, {callback}) *vim.lsp.request()* +request({method}, {params}, {callback}, {bufnr}) *vim.lsp.request()* TODO: Documentation resolve_bufnr({bufnr}) *vim.lsp.resolve_bufnr()* @@ -583,7 +586,7 @@ start_client({config}) *vim.lsp.start_client()* {root_dir} (required, string) Directory where the LSP server will base its rootUri on initialization. - {cmd} (required, list treated like + {cmd} (required, string or list treated like |jobstart()|) Base command that initiates the LSP client. {cmd_cwd} (string, default=|getcwd()|) Directory @@ -687,7 +690,7 @@ stop_client({client_id}, {force}) *vim.lsp.stop_client()* object. To stop all clients: > - vim.lsp.stop_client(lsp.get_active_clients()) + vim.lsp.stop_client(lsp.get_active_clients()) < By default asks the server to shutdown, unless stop was @@ -709,9 +712,6 @@ unsupported_method({method}) *vim.lsp.unsupported_method()* validate_client_config({config}) *vim.lsp.validate_client_config()* TODO: Documentation -validate_command({input}) *vim.lsp.validate_command()* - TODO: Documentation - validate_encoding({encoding}) *vim.lsp.validate_encoding()* TODO: Documentation @@ -751,6 +751,9 @@ transform_schema_to_table() ============================================================================== Lua module: vim.lsp.buf *lsp-buf* +clear_references() *vim.lsp.buf.clear_references()* + TODO: Documentation + code_action({context}) *vim.lsp.buf.code_action()* TODO: Documentation @@ -764,18 +767,30 @@ definition() *vim.lsp.buf.definition()* TODO: Documentation document_highlight() *vim.lsp.buf.document_highlight()* - TODO: Documentation + Send request to server to resolve document highlights for the + current text document position. This request can be associated + to key mapping or to events such as `CursorHold` , eg: +> + vim.api.nvim_command [[autocmd CursorHold lua vim.lsp.buf.document_highlight()]] + vim.api.nvim_command [[autocmd CursorHoldI lua vim.lsp.buf.document_highlight()]] + vim.api.nvim_command [[autocmd CursorMoved lua vim.lsp.buf.clear_references()]] +< document_symbol() *vim.lsp.buf.document_symbol()* TODO: Documentation +execute_command({command}) *vim.lsp.buf.execute_command()* + TODO: Documentation + formatting({options}) *vim.lsp.buf.formatting()* TODO: Documentation -formatting_sync({options}, {timeout_ms}) *vim.lsp.buf.formatting_sync()* - Same as |vim.lsp.buf.formatting()| but synchronous. Useful - for running on save, to make sure buffer is formatted prior - to being saved. {timeout_ms} is passed on to + *vim.lsp.buf.formatting_sync()* +formatting_sync({options}, {timeout_ms}) + Perform |vim.lsp.buf.formatting()| synchronously. + + Useful for running on save, to make sure buffer is formatted + prior to being saved. {timeout_ms} is passed on to |vim.lsp.buf_request_sync()|. hover() *vim.lsp.buf.hover()* @@ -804,8 +819,8 @@ request({method}, {params}, {callback}) *vim.lsp.buf.request()* TODO: Documentation server_ready() *vim.lsp.buf.server_ready()* - Sends a notification through all clients associated with current - buffer and returns `true` if server responds. + Return: ~ + `true` if server responds. signature_help() *vim.lsp.buf.signature_help()* TODO: Documentation @@ -815,10 +830,12 @@ type_definition() *vim.lsp.buf.type_definition()* workspace_symbol({query}) *vim.lsp.buf.workspace_symbol()* Lists all symbols in the current workspace in the quickfix - window. The list is filtered against the optional argument - {query}; if the argument is omitted from the call, the user - is prompted to enter a string on the command line. An empty - string means no filtering is done. + window. + + The list is filtered against the optional argument {query}; if + the argument is omitted from the call, the user is prompted to + enter a string on the command line. An empty string means no + filtering is done. ============================================================================== @@ -829,14 +846,6 @@ err_message({...}) *vim.lsp.callbacks.err_message()* *vim.lsp.callbacks.location_callback()* location_callback({_}, {method}, {result}) - TODO: Documentation - - *vim.lsp.callbacks.log_message()* -log_message({_}, {_}, {result}, {client_id}) - TODO: Documentation - - *vim.lsp.callbacks.signature_help_to_preview_contents()* -signature_help_to_preview_contents({input}) TODO: Documentation @@ -870,8 +879,17 @@ create_and_start_client({cmd}, {cmd_args}, {handlers}, encode_and_send({payload}) *vim.lsp.rpc.encode_and_send()* TODO: Documentation -force_env_list({final_env}) *vim.lsp.rpc.force_env_list()* - TODO: Documentation +env_merge({env}) *vim.lsp.rpc.env_merge()* + Merges current process env with the given env and returns the + result as a list of "k=v" strings. +> + + Example: +< + + > in: { PRODUCTION="false", PATH="/usr/bin/", PORT=123, HOST="0.0.0.0", } + out: { "PRODUCTION=false", "PATH=/usr/bin/", "PORT=123", "HOST=0.0.0.0", } +< *vim.lsp.rpc.format_message_with_content_length()* format_message_with_content_length({encoded_message}) @@ -945,6 +963,10 @@ try_call({errkind}, {fn}, {...}) *vim.lsp.rpc.try_call()* ============================================================================== Lua module: vim.lsp.util *lsp-util* + *vim.lsp.util.apply_syntax_to_region()* +apply_syntax_to_region({ft}, {start}, {finish}) + TODO: Documentation + *vim.lsp.util.apply_text_document_edit()* apply_text_document_edit({text_document_edit}) TODO: Documentation @@ -957,59 +979,61 @@ apply_text_edits({text_edits}, {bufnr}) apply_workspace_edit({workspace_edit}) TODO: Documentation - *vim.lsp.util.diagnostics_by_buf* -diagnostics_by_buf - A table containing diagnostics grouped by buf. - - {: {diagnostics}} - - {diagnostics} is an array of diagnostics. - - By default this is populated by the - `textDocument/publishDiagnostics` callback via - |vim.lsp.util.buf_diagnostics_save_positions|. - - It contains entries for active buffers. Once a buffer is - detached the entries for it are discarded. - buf_clear_diagnostics({bufnr}) *vim.lsp.util.buf_clear_diagnostics()* TODO: Documentation - - *vim.lsp.util.buf_diagnostics_count()* -buf_diagnostics_count({kind}) - Returns the number of diagnostics of given kind for current buffer. - Useful for showing diagnostics counts in statusline. eg: +buf_clear_references({bufnr}) *vim.lsp.util.buf_clear_references()* + TODO: Documentation + +buf_diagnostics_count({kind}) *vim.lsp.util.buf_diagnostics_count()* + Returns the number of diagnostics of given kind for current + buffer. + + Useful for showing diagnostic counts in statusline. eg: > + function! LspStatus() abort let sl = '' - if luaeval('vim.lsp.buf.server_ready()') + if luaeval('not vim.tbl_isempty(vim.lsp.buf_get_clients(0))') let sl.='%#MyStatuslineLSP#E:' - let sl.='%#MyStatuslineLSPErrors#%{luaeval("vim.lsp.util.buf_diagnostics_count(\"Error\")")}' + let sl.='%#MyStatuslineLSPErrors#%{luaeval("vim.lsp.util.buf_diagnostics_count([[Error]])")}' let sl.='%#MyStatuslineLSP# W:' - let sl.='%#MyStatuslineLSPWarnings#%{luaeval("vim.lsp.util.buf_diagnostics_count(\"Warning\")")}' + let sl.='%#MyStatuslineLSPWarnings#%{luaeval("vim.lsp.util.buf_diagnostics_count([[Warning]])")}' else let sl.='%#MyStatuslineLSPErrors#off' endif return sl endfunction - let &l:statusline = '%#MyStatuslineLSP#LSP '.LspStatus() + let &l:statusline = '%#MyStatuslineLSP#LSP '.LspStatus() < Parameters: ~ - {kind} Diagnostic severity kind: Error, Warning, Information or Hint. + {kind} Diagnostic severity kind: See + |vim.lsp.protocol.DiagnosticSeverity| -buf_clear_references({bufnr}) *vim.lsp.util.buf_clear_references()* - TODO: Documentation + Return: ~ + Count of diagnostics - *vim.lsp.util.buf_diagnostics_save()* + *vim.lsp.util.buf_diagnostics_save_positions()* buf_diagnostics_save_positions({bufnr}, {diagnostics}) - Stores the diagnostics into |vim.lsp.util.diagnostics_by_buf| + Saves the diagnostics (Diagnostic[]) into diagnostics_by_buf Parameters: ~ - {bufr} bufnr for which the diagnostics are for. - {diagnostics} Diagnostics[] received from the - langauge server. + {bufnr} bufnr for which the diagnostics are for. + {diagnostics} Diagnostics[] received from the language + server. + + *vim.lsp.util.buf_diagnostics_signs()* +buf_diagnostics_signs({bufnr}, {diagnostics}) + Place signs for each diagnostic in the sign column. + + Sign characters can be customized with the following commands: +> + sign define LspDiagnosticsErrorSign text=E texthl=LspDiagnosticsError linehl= numhl= + sign define LspDiagnosticsWarningSign text=W texthl=LspDiagnosticsWarning linehl= numhl= + sign define LspDiagnosticsInformationSign text=I texthl=LspDiagnosticsInformation linehl= numhl= + sign define LspDiagnosticsHintSign text=H texthl=LspDiagnosticsHint linehl= numhl= +< *vim.lsp.util.buf_diagnostics_underline()* buf_diagnostics_underline({bufnr}, {diagnostics}) @@ -1019,17 +1043,9 @@ buf_diagnostics_underline({bufnr}, {diagnostics}) buf_diagnostics_virtual_text({bufnr}, {diagnostics}) TODO: Documentation - *vim.lsp.util.buf_diagnostics_signs()* -buf_diagnostics_signs({bufnr}, {diagnostics}) - Place signs for each diagnostic in the sign column. - Sign characters can be customized with the following commands: -> -sign define LspDiagnosticsErrorSign text=E texthl=LspDiagnosticsError linehl= numhl= -sign define LspDiagnosticsWarningSign text=W texthl=LspDiagnosticsWarning linehl= numhl= -sign define LspDiagnosticsInformationSign text=I texthl=LspDiagnosticsInformation linehl= numhl= -sign define LspDiagnosticsHintSign text=H texthl=LspDiagnosticsHint linehl= numhl= -< - + *vim.lsp.util.buf_highlight_references()* +buf_highlight_references({bufnr}, {references}) + TODO: Documentation character_offset({buf}, {row}, {col}) *vim.lsp.util.character_offset()* TODO: Documentation @@ -1040,6 +1056,14 @@ close_preview_autocmd({events}, {winnr}) *vim.lsp.util.convert_input_to_markdown_lines()* convert_input_to_markdown_lines({input}, {contents}) + TODO: Documentation + + *vim.lsp.util.convert_signature_help_to_markdown_lines()* +convert_signature_help_to_markdown_lines({signature_help}) + TODO: Documentation + + *vim.lsp.util.diagnostics_group_by_line()* +diagnostics_group_by_line({diagnostics}) TODO: Documentation *vim.lsp.util.extract_completion_items()* @@ -1048,7 +1072,19 @@ extract_completion_items({result}) *vim.lsp.util.fancy_floating_markdown()* fancy_floating_markdown({contents}, {opts}) - TODO: Documentation + Convert markdown into syntax highlighted regions by stripping + the code blocks and converting them into highlighted code. + This will by default insert a blank line separator after those + code block regions to improve readability. The result is shown + in a floating preview TODO: refactor to separate + stripping/converting and make use of open_floating_preview + + Parameters: ~ + {contents} table of lines to show in window + {opts} dictionary with optional fields + + Return: ~ + width,height size of float find_window_by_var({name}, {value}) *vim.lsp.util.find_window_by_var()* TODO: Documentation @@ -1058,10 +1094,33 @@ focusable_float({unique_name}, {fn}) *vim.lsp.util.focusable_float()* *vim.lsp.util.focusable_preview()* focusable_preview({unique_name}, {fn}) + TODO: Documentation + +get_completion_word({item}) *vim.lsp.util.get_completion_word()* TODO: Documentation *vim.lsp.util.get_current_line_to_cursor()* get_current_line_to_cursor() + TODO: Documentation + +get_effective_tabstop({bufnr}) *vim.lsp.util.get_effective_tabstop()* + Get visual width of tabstop. + + Parameters: ~ + {bufnr} (optional, number): Buffer handle, defaults to + current + + Return: ~ + (number) tabstop visual width + + See also: ~ + |softtabstop| + + *vim.lsp.util.get_line_byte_from_position()* +get_line_byte_from_position({bufnr}, {position}) + TODO: Documentation + +get_line_diagnostics() *vim.lsp.util.get_line_diagnostics()* TODO: Documentation *vim.lsp.util.get_severity_highlight_name()* @@ -1071,19 +1130,29 @@ get_severity_highlight_name({severity}) jump_to_location({location}) *vim.lsp.util.jump_to_location()* TODO: Documentation -preview_location({location}) *vim.lsp.util.preview_location()* - TODO: Documentation - locations_to_items({locations}) *vim.lsp.util.locations_to_items()* TODO: Documentation *vim.lsp.util.make_floating_popup_options()* make_floating_popup_options({width}, {height}, {opts}) + TODO: Documentation + + *vim.lsp.util.make_formatting_params()* +make_formatting_params({options}) + TODO: Documentation + +make_position_param() *vim.lsp.util.make_position_param()* TODO: Documentation make_position_params() *vim.lsp.util.make_position_params()* TODO: Documentation +make_range_params() *vim.lsp.util.make_range_params()* + TODO: Documentation + +make_text_document_params() *vim.lsp.util.make_text_document_params()* + TODO: Documentation + npcall({fn}, {...}) *vim.lsp.util.npcall()* TODO: Documentation @@ -1092,15 +1161,49 @@ ok_or_nil({status}, {...}) *vim.lsp.util.ok_or_nil()* *vim.lsp.util.open_floating_preview()* open_floating_preview({contents}, {filetype}, {opts}) + Show contents in a floating window + + Parameters: ~ + {contents} table of lines to show in window + {filetype} string of filetype to set for opened buffer + {opts} dictionary with optional fields + + Return: ~ + bufnr,winnr buffer and window number of floating window or + nil + +parse_snippet({input}) *vim.lsp.util.parse_snippet()* + TODO: Documentation + +parse_snippet_rec({input}, {inner}) *vim.lsp.util.parse_snippet_rec()* + TODO: Documentation + +preview_location({location}) *vim.lsp.util.preview_location()* + Preview a location in a floating windows + + behavior depends on type of location: + • for Location, range is shown (e.g., function definition) + • for LocationLink, targetRange is shown (e.g., body of + function definition) + + Parameters: ~ + {location} a single Location or LocationLink + + Return: ~ + bufnr,winnr buffer and window number of floating window or + nil + + *vim.lsp.util.remove_unmatch_completion_items()* +remove_unmatch_completion_items({items}, {prefix}) TODO: Documentation set_lines({lines}, {A}, {B}, {new_lines}) *vim.lsp.util.set_lines()* TODO: Documentation -set_loclist({locations}) *vim.lsp.util.set_loclist()* +set_loclist({items}) *vim.lsp.util.set_loclist()* TODO: Documentation -set_qflist({locations}) *vim.lsp.util.set_qflist()* +set_qflist({items}) *vim.lsp.util.set_qflist()* TODO: Documentation show_line_diagnostics() *vim.lsp.util.show_line_diagnostics()* @@ -1109,11 +1212,20 @@ show_line_diagnostics() *vim.lsp.util.show_line_diagnostics()* sort_by_key({fn}) *vim.lsp.util.sort_by_key()* TODO: Documentation +sort_completion_items({items}) *vim.lsp.util.sort_completion_items()* + TODO: Documentation + split_lines({value}) *vim.lsp.util.split_lines()* TODO: Documentation +symbols_to_items({symbols}, {bufnr}) *vim.lsp.util.symbols_to_items()* + Convert symbols to quickfix list items + + Parameters: ~ + {symbols} DocumentSymbol[] or SymbolInformation[] + *vim.lsp.util.text_document_completion_list_to_complete_items()* -text_document_completion_list_to_complete_items({result}) +text_document_completion_list_to_complete_items({result}, {prefix}) TODO: Documentation trim_empty_lines({lines}) *vim.lsp.util.trim_empty_lines()* @@ -1123,7 +1235,4 @@ trim_empty_lines({lines}) *vim.lsp.util.trim_empty_lines()* try_trim_markdown_code_blocks({lines}) TODO: Documentation -validate_lsp_position({pos}) *vim.lsp.util.validate_lsp_position()* - TODO: Documentation - vim:tw=78:ts=8:ft=help:norl: diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt index 00126f668b..002fc523a1 100644 --- a/runtime/doc/lua.txt +++ b/runtime/doc/lua.txt @@ -1031,6 +1031,9 @@ inspect({object}, {options}) *vim.inspect()* https://github.com/kikito/inspect.lua https://github.com/mpeterv/vinspect +make_meta_accessor({get}, {set}, {del}) *vim.make_meta_accessor()* + TODO: Documentation + paste({lines}, {phase}) *vim.paste()* Paste handler, invoked by |nvim_paste()| when a conforming UI (such as the |TUI|) pastes text into the editor. @@ -1146,7 +1149,7 @@ list_extend({dst}, {src}, {start}, {finish}) *vim.list_extend()* |vim.tbl_extend()| pesc({s}) *vim.pesc()* - Escapes magic chars in a Lua pattern string. + Escapes magic chars in a Lua pattern. Parameters: ~ {s} String to escape @@ -1190,8 +1193,7 @@ startswith({s}, {prefix}) *vim.startswith()* 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 = - 1 }` + example: tbl_add_reverse_lookup { A = 1 } == { [1] = 'A , A = 1 }` Parameters: ~ {o} table The table to add the reverse to. @@ -1206,6 +1208,37 @@ tbl_contains({t}, {value}) *vim.tbl_contains()* Return: ~ true if `t` contains `value` +tbl_count({t}) *vim.tbl_count()* + Counts the number of non-nil values in table `t` . +> + + vim.tbl_count({ a=1, b=2 }) => 2 + vim.tbl_count({ 1, 2 }) => 2 +< + + Parameters: ~ + {t} Table + + Return: ~ + Number that is the number of the value in table + + See also: ~ + https://github.com/Tieske/Penlight/blob/master/lua/pl/tablex.lua + +tbl_deep_extend({behavior}, {...}) *vim.tbl_deep_extend()* + Merges recursively two or more map-like tables. + + Parameters: ~ + {behavior} Decides what to do if a key is found in more + than one map: + • "error": raise an error + • "keep": use value from the leftmost map + • "force": use value from the rightmost map + {...} Two or more map-like tables. + + See also: ~ + |tbl_extend()| + tbl_extend({behavior}, {...}) *vim.tbl_extend()* Merges two or more map-like tables. @@ -1220,6 +1253,13 @@ tbl_extend({behavior}, {...}) *vim.tbl_extend()* See also: ~ |extend()| +tbl_filter({func}, {t}) *vim.tbl_filter()* + Filter a table using a predicate function + + Parameters: ~ + {func} function or callable table + {t} table + tbl_flatten({t}) *vim.tbl_flatten()* Creates a copy of a list-like table such that any nested tables are "unrolled" and appended to the result. @@ -1238,11 +1278,19 @@ tbl_isempty({t}) *vim.tbl_isempty()* Fromhttps://github.com/premake/premake-core/blob/master/src/base/table.lua@paramt Table to check tbl_islist({t}) *vim.tbl_islist()* - Table + Determine whether a Lua table can be treated as an array. + + An empty table `{}` will default to being treated as an array. + Use `vim.emtpy_dict()` to create a table treated as an empty + dict. Empty tables returned by `rpcrequest()` and `vim.fn` + functions can be checked using this function whether they + represent empty API arrays and vimL lists. + + Parameters: ~ + {t} Table Return: ~ - true: A non-empty array, false: A non-empty table, nil: An - empty table + `true` if array-like table, else `false` . tbl_keys({t}) *vim.tbl_keys()* Return a list of all keys used in a table. However, the order @@ -1257,6 +1305,13 @@ tbl_keys({t}) *vim.tbl_keys()* See also: ~ Fromhttps://github.com/premake/premake-core/blob/master/src/base/table.lua +tbl_map({func}, {t}) *vim.tbl_map()* + Apply a function to all values of a table. + + Parameters: ~ + {func} function or callable table + {t} table + tbl_values({t}) *vim.tbl_values()* Return a list of all values used in a table. However, the order of the return table of values is not guaranteed. @@ -1301,12 +1356,12 @@ validate({opt}) *vim.validate()* => NOP (success) < > - vim.validate{arg1={1, 'table'}} - => error('arg1: expected table, got number') + vim.validate{arg1={1, 'table'}} + => error('arg1: expected table, got number') < > - vim.validate{arg1={3, function(a) return (a % 2) == 0 end, 'even number'}} - => error('arg1: expected even number, got 3') + vim.validate{arg1={3, function(a) return (a % 2) == 0 end, 'even number'}} + => error('arg1: expected even number, got 3') < Parameters: ~ diff --git a/runtime/lua/vim/lsp.lua b/runtime/lua/vim/lsp.lua index e759511347..7442f0c0b5 100644 --- a/runtime/lua/vim/lsp.lua +++ b/runtime/lua/vim/lsp.lua @@ -877,11 +877,11 @@ function lsp.buf_request_sync(bufnr, method, params, timeout_ms) end --- Send a notification to a server --- @param bufnr [number] (optional): The number of the buffer --- @param method [string]: Name of the request method --- @param params [string]: Arguments to send to the server --- --- @returns true if any client returns true; false otherwise +--@param bufnr [number] (optional): The number of the buffer +--@param method [string]: Name of the request method +--@param params [string]: Arguments to send to the server +--- +--@returns true if any client returns true; false otherwise function lsp.buf_notify(bufnr, method, params) validate { bufnr = { bufnr, 'n', true }; diff --git a/runtime/lua/vim/lsp/buf.lua b/runtime/lua/vim/lsp/buf.lua index e1ddfb7efa..839e00c67d 100644 --- a/runtime/lua/vim/lsp/buf.lua +++ b/runtime/lua/vim/lsp/buf.lua @@ -23,6 +23,9 @@ local function request(method, params, callback) return vim.lsp.buf_request(0, method, params, callback) end +--- Sends a notification through all clients associated with current buffer. +-- +--@return `true` if server responds. function M.server_ready() return not not vim.lsp.buf_notify(0, "window/progress", {}) end @@ -69,6 +72,10 @@ function M.formatting(options) return request('textDocument/formatting', params) end +--- Perform |vim.lsp.buf.formatting()| synchronously. +--- +--- Useful for running on save, to make sure buffer is formatted prior to being +--- saved. {timeout_ms} is passed on to |vim.lsp.buf_request_sync()|. function M.formatting_sync(options, timeout_ms) local params = util.make_formatting_params(options) local result = vim.lsp.buf_request_sync(0, "textDocument/formatting", params, timeout_ms) @@ -136,6 +143,12 @@ function M.document_symbol() request('textDocument/documentSymbol', params) end + +--- Lists all symbols in the current workspace in the quickfix window. +--- +--- The list is filtered against the optional argument {query}; +--- if the argument is omitted from the call, the user is prompted to enter a string on the command line. +--- An empty string means no filtering is done. function M.workspace_symbol(query) query = query or npcall(vfn.input, "Query: ") local params = {query = query} diff --git a/runtime/lua/vim/lsp/rpc.lua b/runtime/lua/vim/lsp/rpc.lua index dad1dc11f1..81c92bfe05 100644 --- a/runtime/lua/vim/lsp/rpc.lua +++ b/runtime/lua/vim/lsp/rpc.lua @@ -36,10 +36,12 @@ end --- Merges current process env with the given env and returns the result as --- a list of "k=v" strings. --- +--- 
 --- Example:
 ---
----      { PRODUCTION="false", PATH="/usr/bin/", PORT=123, HOST="0.0.0.0", }
----   => { "PRODUCTION=false", "PATH=/usr/bin/", "PORT=123", "HOST=0.0.0.0", }
+---  in:    { PRODUCTION="false", PATH="/usr/bin/", PORT=123, HOST="0.0.0.0", }
+---  out:   { "PRODUCTION=false", "PATH=/usr/bin/", "PORT=123", "HOST=0.0.0.0", }
+---
local function env_merge(env) if env == nil then return env diff --git a/runtime/lua/vim/lsp/util.lua b/runtime/lua/vim/lsp/util.lua index ab2992ba60..6b19d3ecd6 100644 --- a/runtime/lua/vim/lsp/util.lua +++ b/runtime/lua/vim/lsp/util.lua @@ -952,7 +952,9 @@ do end --- Saves the diagnostics (Diagnostic[]) into diagnostics_by_buf - -- + --- + --@param bufnr bufnr for which the diagnostics are for. + --@param diagnostics Diagnostics[] received from the language server. function M.buf_diagnostics_save_positions(bufnr, diagnostics) validate { bufnr = {bufnr, 'n', true}; @@ -1044,6 +1046,29 @@ do end end + --- Returns the number of diagnostics of given kind for current buffer. + --- + --- Useful for showing diagnostic counts in statusline. eg: + --- + --- 
+  --- function! LspStatus() abort
+  ---     let sl = ''
+  ---     if luaeval('not vim.tbl_isempty(vim.lsp.buf_get_clients(0))')
+  ---         let sl.='%#MyStatuslineLSP#E:'
+  ---         let sl.='%#MyStatuslineLSPErrors#%{luaeval("vim.lsp.util.buf_diagnostics_count([[Error]])")}'
+  ---         let sl.='%#MyStatuslineLSP# W:'
+  ---         let sl.='%#MyStatuslineLSPWarnings#%{luaeval("vim.lsp.util.buf_diagnostics_count([[Warning]])")}'
+  ---     else
+  ---         let sl.='%#MyStatuslineLSPErrors#off'
+  ---     endif
+  ---     return sl
+  --- endfunction
+  --- let &l:statusline = '%#MyStatuslineLSP#LSP '.LspStatus()
+  ---
+ --- + --@param kind Diagnostic severity kind: See |vim.lsp.protocol.DiagnosticSeverity| + --- + --@return Count of diagnostics function M.buf_diagnostics_count(kind) local bufnr = vim.api.nvim_get_current_buf() local diagnostics = M.diagnostics_by_buf[bufnr] @@ -1064,6 +1089,16 @@ do [protocol.DiagnosticSeverity.Hint] = "LspDiagnosticsHintSign"; } + --- Place signs for each diagnostic in the sign column. + --- + --- Sign characters can be customized with the following commands: + --- + --- 
+  --- sign define LspDiagnosticsErrorSign text=E texthl=LspDiagnosticsError linehl= numhl=
+  --- sign define LspDiagnosticsWarningSign text=W texthl=LspDiagnosticsWarning linehl= numhl=
+  --- sign define LspDiagnosticsInformationSign text=I texthl=LspDiagnosticsInformation linehl= numhl=
+  --- sign define LspDiagnosticsHintSign text=H texthl=LspDiagnosticsHint linehl= numhl=
+  ---
function M.buf_diagnostics_signs(bufnr, diagnostics) for _, diagnostic in ipairs(diagnostics) do vim.fn.sign_place(0, sign_ns, diagnostic_severity_map[diagnostic.severity], bufnr, {lnum=(diagnostic.range.start.line+1)}) @@ -1142,7 +1177,7 @@ end --- Convert symbols to quickfix list items --- ---@symbols DocumentSymbol[] or SymbolInformation[] +--@param symbols DocumentSymbol[] or SymbolInformation[] function M.symbols_to_items(symbols, bufnr) local function _symbols_to_items(_symbols, _items, _bufnr) for _, symbol in ipairs(_symbols) do diff --git a/runtime/lua/vim/shared.lua b/runtime/lua/vim/shared.lua index 384d22cb89..6e427665f2 100644 --- a/runtime/lua/vim/shared.lua +++ b/runtime/lua/vim/shared.lua @@ -347,16 +347,16 @@ function vim.tbl_flatten(t) return result end --- Determine whether a Lua table can be treated as an array. --- --- An empty table `{}` will default to being treated as an array. --- Use `vim.emtpy_dict()` to create a table treated as an --- empty dict. Empty tables returned by `rpcrequest()` and --- `vim.fn` functions can be checked using this function --- whether they represent empty API arrays and vimL lists. +--- Determine whether a Lua table can be treated as an array. --- ---@params Table ---@returns true: An array-like table, false: A dict-like or mixed table +--- An empty table `{}` will default to being treated as an array. +--- Use `vim.emtpy_dict()` to create a table treated as an +--- empty dict. Empty tables returned by `rpcrequest()` and +--- `vim.fn` functions can be checked using this function +--- whether they represent empty API arrays and vimL lists. +--- +--@param t Table +--@returns `true` if array-like table, else `false`. function vim.tbl_islist(t) if type(t) ~= 'table' then return false @@ -392,7 +392,7 @@ end --- --- --@see https://github.com/Tieske/Penlight/blob/master/lua/pl/tablex.lua ---@param Table +--@param t Table --@returns Number that is the number of the value in table function vim.tbl_count(t) vim.validate{t={t,'t'}} diff --git a/scripts/gen_vimdoc.py b/scripts/gen_vimdoc.py index 3c51b2aa81..328a903b46 100755 --- a/scripts/gen_vimdoc.py +++ b/scripts/gen_vimdoc.py @@ -374,6 +374,7 @@ def update_params_map(parent, ret_map, width=62): def render_node(n, text, prefix='', indent='', width=62): """Renders a node as Vim help text, recursively traversing all descendants.""" global fmt_vimhelp + global has_seen_preformatted def ind(s): return s if fmt_vimhelp else '' @@ -386,6 +387,7 @@ def render_node(n, text, prefix='', indent='', width=62): o = get_text(n, preformatted=True) ensure_nl = '' if o[-1] == '\n' else '\n' text += '>{}{}\n<'.format(ensure_nl, o) + elif is_inline(n): text = doc_wrap(get_text(n), indent=indent, width=width) elif n.nodeName == 'verbatim': @@ -394,11 +396,17 @@ def render_node(n, text, prefix='', indent='', width=62): text += ' [verbatim] {}'.format(get_text(n)) elif n.nodeName == 'listitem': for c in n.childNodes: - text += ( - indent - + prefix - + render_node(c, text, indent=indent + (' ' * len(prefix)), width=width) + result = render_node( + c, + text, + indent=indent + (' ' * len(prefix)), + width=width ) + + if is_blank(result): + continue + + text += indent + prefix + result elif n.nodeName in ('para', 'heading'): for c in n.childNodes: text += render_node(c, text, indent=indent, width=width) @@ -433,6 +441,7 @@ def render_node(n, text, prefix='', indent='', width=62): else: raise RuntimeError('unhandled node type: {}\n{}'.format( n.nodeName, n.toprettyxml(indent=' ', newl='\n'))) + return text @@ -496,6 +505,7 @@ def para_as_map(parent, indent='', width=62): and '' != get_text(self_or_child(child)).strip() and ' ' != text[-1]): text += ' ' + text += render_node(child, text, indent=indent, width=width) prev = child @@ -566,6 +576,7 @@ def fmt_node_as_vimhelp(parent, width=62, indent=''): rendered_blocks.append(clean_lines('\n'.join(chunks).strip())) rendered_blocks.append('') + return clean_lines('\n'.join(rendered_blocks).strip()) @@ -678,6 +689,11 @@ def extract_from_xml(filename, target, width): signature += vimtag.rjust(width - len(signature)) paras = [] + brief_desc = find_first(member, 'briefdescription') + if brief_desc: + for child in brief_desc.childNodes: + paras.append(para_as_map(child)) + desc = find_first(member, 'detaileddescription') if desc: for child in desc.childNodes: @@ -763,8 +779,36 @@ def fmt_doxygen_xml_as_vimhelp(filename, target): func_doc = fn['signature'] + '\n' func_doc += textwrap.indent(clean_lines(doc), ' ' * 16) + + # Verbatim handling. func_doc = re.sub(r'^\s+([<>])$', r'\1', func_doc, flags=re.M) + split_lines = func_doc.split('\n') + start = 0 + while True: + try: + start = split_lines.index('>', start) + except ValueError: + break + + try: + end = split_lines.index('<', start) + except ValueError: + break + + split_lines[start + 1:end] = [ + (' ' + x).rstrip() + for x in textwrap.dedent( + "\n".join( + split_lines[start+1:end] + ) + ).split("\n") + ] + + start = end + + func_doc = "\n".join(split_lines) + if 'Deprecated' in xrefs: deprecated_fns_txt[name] = func_doc elif name.startswith(CONFIG[target]['fn_name_prefix']): @@ -847,11 +891,21 @@ def main(config): groupxml = os.path.join(base, '%s.xml' % compound.getAttribute('refid')) - desc = find_first(minidom.parse(groupxml), 'detaileddescription') + group_parsed = minidom.parse(groupxml) + doc_list = [] + brief_desc = find_first(group_parsed, 'briefdescription') + if brief_desc: + for child in brief_desc.childNodes: + doc_list.append(fmt_node_as_vimhelp(child)) + + desc = find_first(group_parsed, 'detaileddescription') if desc: doc = fmt_node_as_vimhelp(desc) + if doc: - intros[groupname] = doc + doc_list.append(doc) + + intros[groupname] = "\n".join(doc_list) for compound in dom.getElementsByTagName('compound'): if compound.getAttribute('kind') != 'file': diff --git a/scripts/lua2dox_filter b/scripts/lua2dox_filter index 6cb16ef060..61577527c4 100755 --- a/scripts/lua2dox_filter +++ b/scripts/lua2dox_filter @@ -36,7 +36,16 @@ test_executable(){ ##! \brief sets the lua interpreter set_lua(){ - test_executable 'texlua' + if test -z "${EXE}" + then + test_executable 'luajit' + fi + + if test -z "${EXE}" + then + test_executable 'texlua' + fi + if test -z "${EXE}" then test_executable 'lua' diff --git a/src/nvim/api/buffer.c b/src/nvim/api/buffer.c index 18474c6588..8e61976c4b 100644 --- a/src/nvim/api/buffer.c +++ b/src/nvim/api/buffer.c @@ -42,6 +42,8 @@ /// \defgroup api-buffer /// +/// \brief For more information on buffers, see |buffers| +/// /// Unloaded Buffers:~ /// /// Buffers may be unloaded by the |:bunload| command or the buffer's diff --git a/src/nvim/lua/vim.lua b/src/nvim/lua/vim.lua index 523d23ec12..047ce1ad43 100644 --- a/src/nvim/lua/vim.lua +++ b/src/nvim/lua/vim.lua @@ -255,6 +255,8 @@ function vim.schedule_wrap(cb) end) end +--- +--@private function vim.empty_dict() return setmetatable({}, vim._empty_dict_mt) end