gen_vimdoc.py: generate LSP docs

runtime/doc/api.txt

@@ -569,7 +569,8 @@ nvim_call_atomic({calls})                                 *nvim_call_atomic()*
                     occurred, the values from all preceding calls will still
                     be returned.
 
-nvim_call_dict_function({dict}, {fn}, {args})      *nvim_call_dict_function()*
+                                                   *nvim_call_dict_function()*
+nvim_call_dict_function({dict}, {fn}, {args})
                 Calls a VimL |Dictionary-function| with the given arguments.
 
                 On execution error: fails with VimL error, does not update
@@ -1878,7 +1879,8 @@ nvim_buf_get_var({buffer}, {name})                        *nvim_buf_get_var()*
                 Return: ~
                     Variable value
 
-nvim_buf_get_virtual_text({buffer}, {lnum})      *nvim_buf_get_virtual_text()*
+                                                 *nvim_buf_get_virtual_text()*
+nvim_buf_get_virtual_text({buffer}, {lnum})
                 Get the virtual text (annotation) for a buffer line.
 
                 The virtual text is returned as list of lists, whereas the
@@ -2300,7 +2302,8 @@ nvim_tabpage_list_wins({tabpage})                   *nvim_tabpage_list_wins()*
                 Return: ~
                     List of windows in `tabpage`
 
-nvim_tabpage_set_var({tabpage}, {name}, {value})      *nvim_tabpage_set_var()*
+                                                      *nvim_tabpage_set_var()*
+nvim_tabpage_set_var({tabpage}, {name}, {value})
                 Sets a tab-scoped (t:) variable
 
                 Parameters: ~

runtime/lua/vim/lsp.lua

@@ -204,95 +204,155 @@ local function text_document_did_open_handler(bufnr, client)
   client.notify('textDocument/didOpen', params)
 end
 
+--- LSP client object.
+---
+--- - Methods:
+---
+---  - request(method, params, [callback])
+---     Send a request to the server. If callback is not specified, it will use
+---     {client.callbacks} to try to find a callback. If one is not found there,
+---     then an error will occur.
+---     This is a thin wrapper around {client.rpc.request} with some additional
+---     checking.
+---     Returns a boolean to indicate if the notification was successful. If it
+---     is false, then it will always be false (the client has shutdown).
+---     If it was successful, then it will return the request id as the second
+---     result. You can use this with `notify("$/cancel", { id = request_id })`
+---     to cancel the request. This helper is made automatically with
+---     |vim.lsp.buf_request()|
+---     Returns: status, [client_id]
+---
+---  - notify(method, params)
+---     This is just {client.rpc.notify}()
+---     Returns a boolean to indicate if the notification was successful. If it
+---     is false, then it will always be false (the client has shutdown).
+---     Returns: status
+---
+---  - cancel_request(id)
+---     This is just {client.rpc.notify}("$/cancelRequest", { id = id })
+---     Returns the same as `notify()`.
+---
+---  - stop([force])
+---     Stop 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()
+---     Returns true if the client is fully stopped.
+---
+--- - 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.
+---
+---  - offset_encoding (string): The encoding used for communicating
+---    with the server. You can modify this in the `on_init` method
+---    before text is sent to the server.
+---
+---  - callbacks (table): The callbacks used by the client as
+---    described in |lsp-callbacks|.
+---
+---  - config (table): copy 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.
+---
+---  - resolved_capabilities (table): Normalized table of
+---    capabilities that we have detected based on the initialize
+---    response from the server in `server_capabilities`.
+function lsp.client()
+  error()
+end
 
 --- Start a client and initialize it.
--- Its arguments are passed via a configuration object.
+--- Its arguments are passed via a configuration object.
---
+---
--- Mandatory parameters:
+--- Mandatory parameters:
---
+---
--- root_dir: {string} specifying the directory where the LSP server will base
+--- root_dir: {string} specifying the directory where the LSP server will base
--- as its rootUri on initialization.
+--- as its rootUri on initialization.
---
+---
--- cmd: {string} or {list} which is the base command to execute for the LSP. A
+--- cmd: {string} or {list} which is the base command to execute for the LSP. A
--- string will be run using |'shell'| and a list will be interpreted as a bare
+--- string will be run using 'shell' and a list will be interpreted as a bare
--- command with arguments passed. This is the same as |jobstart()|.
+--- command with arguments passed. This is the same as |jobstart()|.
---
+---
--- Optional parameters:
+--@param cmd_cwd: {string} specifying the directory to launch the `cmd` process. This
-
+--- is not related to `root_dir`. By default, |getcwd()| is used.
--- cmd_cwd: {string} specifying the directory to launch the `cmd` process. This
+---
--- is not related to `root_dir`. By default, |getcwd()| is used.
+--@param cmd_env: {table} specifying the environment flags to pass to the LSP on
---
+--- spawn.  This can be specified using keys like a map or as a list with `k=v`
--- cmd_env: {table} specifying the environment flags to pass to the LSP on
+--- pairs or both. Non-string values are coerced to a string.
--- spawn.  This can be specified using keys like a map or as a list with `k=v`
+--- For example: `{ "PRODUCTION=true"; "TEST=123"; PORT = 8080; HOST = "0.0.0.0"; }`.
--- pairs or both. Non-string values are coerced to a string.
+---
--- For example: `{ "PRODUCTION=true"; "TEST=123"; PORT = 8080; HOST = "0.0.0.0"; }`.
+--@param capabilities: Map overriding the default capabilities defined by
---
+--- |vim.lsp.protocol.make_client_capabilities()|, passed to the language
--- capabilities: A {table} which will be used instead of
+--- server on initialization. Hint: use make_client_capabilities() and modify
--- `vim.lsp.protocol.make_client_capabilities()` which contains neovim's
+--- its result.
--- default capabilities and passed to the language server on initialization.
+--- - Note: To send an empty dictionary use
--- You'll probably want to use make_client_capabilities() and modify the
+---   `{[vim.type_idx]=vim.types.dictionary}`, else it will be encoded as an
--- result.
+---   array.
--- NOTE:
+---
---   To send an empty dictionary, you should use
+--@param callbacks: Map of language server method names to
---   `{[vim.type_idx]=vim.types.dictionary}` Otherwise, it will be encoded as
+--- `function(err, method, params, client_id)` handler.
---   an array.
+--- Invoked for:
---
+--- - Notifications from the server, where `err` will always be `nil`.
--- callbacks: A {table} of whose keys are language server method names and the
+--- - Requests initiated by the server. For these you can respond by returning
--- values are `function(err, method, params, client_id)`.
+---   two values: `result, err` where err must be shaped like a RPC error,
--- This will be called for:
+---   i.e. `{ code, message, data? }`. Use |vim.lsp.rpc_response_error()| to
--- - notifications from the server, where `err` will always be `nil`
+---   help with this.
--- - requests initiated by the server. For these, you can respond by returning
+--- - Default callback for client requests not explicitly specifying
--- two values: `result, err`. The err must be in the format of an RPC error,
+---   a callback.
--- which is `{ code, message, data? }`. You can use |vim.lsp.rpc_response_error()|
+---
--- to help with this.
+--@param init_options values to pass in the initialization request
--- - as a callback for requests initiated by the client if the request doesn't
+--- as `initializationOptions`. See `initialize` in the LSP spec.
--- explicitly specify a callback.
+---
---
+--@param name: string used in log messages. Defaults to {client_id}
--- init_options: A {table} of values to pass in the initialization request
+---
--- as `initializationOptions`. See the `initialize` in the LSP spec.
+--@param offset_encoding: One of "utf-8", "utf-16", or "utf-32" which is the
---
+--- encoding that the LSP server expects. By default, it is "utf-16" as
--- name: A {string} used in log messages. Defaults to {client_id}
+--- specified in the LSP specification. The client does not verify this
---
+--- is correct.
--- offset_encoding: One of 'utf-8', 'utf-16', or 'utf-32' which is the
+---
--- encoding that the LSP server expects. By default, it is 'utf-16' as
+--@param on_error Callback with parameters (code, ...), invoked
--- specified in the LSP specification. The client does not verify this
+--- when the client operation throws an error.
--- is correct.
+--- {code} is a number describing the error. Other arguments may be
---
+--- passed depending on the error kind.  See |vim.lsp.client_errors| for
--- on_error(code, ...): A function for handling errors thrown by client
+--- possible errors. Use `vim.lsp.client_errors[code]` to get human-friendly
--- operation. {code} is a number describing the error. Other arguments may be
+--- name.
--- passed depending on the error kind.  @see |vim.lsp.client_errors| for
+---
--- possible errors. `vim.lsp.client_errors[code]` can be used to retrieve a
+--@param before_init Callback with parameters (initialize_params, config) invoked
--- human understandable string.
+--- before the LSP "initialize" phase, where `params` contains the
---
+--- parameters being sent to the server and `config` is the config
--- before_init(initialize_params, config): A function which is called *before*
+--- that was passed to `start_client()`. You can use this to modify
--- the request `initialize` is completed. `initialize_params` contains
+--- parameters before they are sent.
--- the parameters we are sending to the server and `config` is the config that
+---
--- was passed to `start_client()` for convenience. You can use this to modify
+--@param on_init Callback (client, initialize_result) invoked after LSP
--- parameters before they are sent.
+--- "initialize", where `result` is a table of `capabilities` and
---
+--- anything else the server may send. For example, clangd sends
--- on_init(client, initialize_result): A function which is called after the
+--- `initialize_result.offsetEncoding` if `capabilities.offsetEncoding` was
--- request `initialize` is completed. `initialize_result` contains
+--- sent to it. You can only modify the `client.offset_encoding` here before
--- `capabilities` and anything else the server may send. For example, `clangd`
+--- any notifications are sent.
--- sends `result.offsetEncoding` if `capabilities.offsetEncoding` was sent to
+---
--- it.
+--@param on_exit Callback (code, signal, client_id) invoked on client
---
+--- exit.
--- on_exit(code, signal, client_id): A function which is called after the
+--- - code: exit code of the process
--- client has exited. code is the exit code of the process, and signal is a
+--- - signal: number describing the signal used to terminate (if any)
--- number describing the signal used to terminate (if any).
+--- - client_id: client handle
---
+---
--- on_attach(client, bufnr): A function which is called after the client is
+--@param on_attach Callback (client, bufnr) invoked when client
--- attached to a buffer.
+--- attaches to a buffer.
---
+---
--- trace:  'off' | 'messages' | 'verbose' | nil passed directly to the language
+--@param trace:  "off" | "messages" | "verbose" | nil passed directly to the language
--- server in the initialize request. Invalid/empty values will default to 'off'
+--- server in the initialize request. Invalid/empty values will default to "off"
---
+---
--- @returns client_id You can use |vim.lsp.get_client_by_id()| to get the
+--@returns Client id. |vim.lsp.get_client_by_id()| Note: client is only
--- actual client.
+--- available after it has been initialized, which may happen after a small
---
+--- delay (or never if there is an error). Use `on_init` to do any actions once
--- NOTE: The client is only available *after* it has been initialized, which
+--- the client has been initialized.
--- may happen after a small delay (or never if there is an error).
--- For this reason, you may want to use `on_init` to do any actions once the
--- client has been initialized.
 function lsp.start_client(config)
   local cleaned_config = validate_client_config(config)
   local cmd, cmd_args, offset_encoding = cleaned_config.cmd, cleaned_config.cmd_args, cleaned_config.offset_encoding
@@ -402,8 +462,8 @@ function lsp.start_client(config)
       initializationOptions = config.init_options;
       -- The capabilities provided by the client (editor or tool)
       capabilities = config.capabilities or protocol.make_client_capabilities();
-      -- The initial trace setting. If omitted trace is disabled ('off').
+      -- The initial trace setting. If omitted trace is disabled ("off").
-      -- trace = 'off' | 'messages' | 'verbose';
+      -- trace = "off" | "messages" | "verbose";
       trace = valid_traces[config.trace] or 'off';
       -- The workspace folders configured in the client when the server starts.
       -- This property is only available if the client supports workspace folders.
@@ -634,10 +694,13 @@ function lsp._text_document_did_save_handler(bufnr)
   end)
 end
 
--- Implements the textDocument/did* notifications required to track a buffer
+--- Implements the `textDocument/did…` notifications required to track a buffer
--- for any language server.
+--- for any language server.
--- @param bufnr [number] buffer handle or 0 for current
+---
--- @param client_id [number] the client id
+--- Without calling this, the server won't be notified of changes to a buffer.
+---
+--- @param bufnr (number) Buffer handle, or 0 for current
+--- @param client_id (number) Client id
 function lsp.buf_attach_client(bufnr, client_id)
   validate {
     bufnr     = {bufnr, 'n', true};
@@ -683,28 +746,33 @@ function lsp.buf_attach_client(bufnr, client_id)
   return true
 end
 
--- Check if a buffer is attached for a particular client.
+--- Checks if a buffer is attached for a particular client.
--- @param bufnr [number] buffer handle or 0 for current
+---
--- @param client_id [number] the client id
+---@param bufnr (number) Buffer handle, or 0 for current
+---@param client_id (number) the client id
 function lsp.buf_is_attached(bufnr, client_id)
   return (all_buffer_active_clients[bufnr] or {})[client_id] == true
 end
 
--- Look up an active client by its id, returns nil if it is not yet initialized
+--- Gets an active client by id, or nil if the id is invalid or the
--- or is not a valid id.
+--- client is not yet initialized.
--- @param client_id number the client id.
+---
+--@param client_id client id number
+---
+--@return |vim.lsp.client| object, or nil
 function lsp.get_client_by_id(client_id)
   return active_clients[client_id]
 end
 
--- Stop a client by its id, optionally with force.
+--- Stops a client.
--- You can also use the `stop()` function on a client if you already have
+---
--- access to it.
+--- You can also use the `stop()` function on a |vim.lsp.client| object.
--- 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,
+--- By default asks the server to shutdown, unless stop was requested
--- it will automatically force shutdown.
+--- already for this client, then force-shutdown is attempted.
--- @param client_id number the client id.
+---
--- @param force boolean (optional) whether to use force or request shutdown
+--@param client_id client id number
+--@param force boolean (optional) shutdown forcefully
 function lsp.stop_client(client_id, force)
   local client
   client = active_clients[client_id]
@@ -718,18 +786,16 @@ function lsp.stop_client(client_id, force)
   end
 end
 
--- Returns a list of all the active clients.
+--- Gets all active clients.
+---
+--@return Table of |vim.lsp.client| objects
 function lsp.get_active_clients()
   return vim.tbl_values(active_clients)
 end
 
--- Stop all the clients, optionally with force.
+--- Stops all clients.
--- You can also use the `stop()` function on a client if you already have
+---
--- access to it.
+--@param force boolean (optional) shutdown forcefully
--- 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 force shutdown.
--- @param force boolean (optional) whether to use force or request shutdown
 function lsp.stop_all_clients(force)
   for _, client in pairs(uninitialized_clients) do
     client.stop(true)
@@ -761,17 +827,21 @@ end
 
 nvim_command("autocmd VimLeavePre * lua vim.lsp._vim_exit_handler()")
 
----
---- Buffer level client functions.
----
 
---- Send a request to a server and return the response
+--- Sends an async request for all active clients attached to the
--- @param bufnr [number] Buffer handle or 0 for current.
+--- buffer.
--- @param method [string] Request method name
+---
--- @param params [table|nil] Parameters to send to the server
+--@param bufnr (number) Buffer handle, or 0 for current.
--- @param callback [function|nil] Request callback (or uses the client's callbacks)
+--@param method (string) LSP method name
+--@param params (optional, table) Parameters to send to the server
+--@param callback (optional, functionnil) Handler
+--  `function(err, method, params, client_id)` for this request. Defaults
+--  to the client callback in `client.callbacks`. See |lsp-callbacks|.
 --
--- @returns: client_request_ids, cancel_all_requests
+--@returns 2-tuple:
+---  - Map of client-id:request-id pairs for all successful requests.
+---  - Function which can be used to cancel all the requests. You could instead
+---    iterate all clients and call their `cancel_request()` methods.
 function lsp.buf_request(bufnr, method, params, callback)
   validate {
     bufnr    = { bufnr, 'n', true };
@@ -789,31 +859,39 @@ function lsp.buf_request(bufnr, method, params, callback)
     end
   end)
 
-  local function cancel_all_requests()
+  local function _cancel_all_requests()
     for client_id, request_id in pairs(client_request_ids) do
       local client = active_clients[client_id]
       client.cancel_request(request_id)
     end
   end
 
-  return client_request_ids, cancel_all_requests
+  return client_request_ids, _cancel_all_requests
 end
 
---- Send a request to a server and wait for the response.
+--- Sends a request to a server and waits for the response.
--- @param bufnr [number] Buffer handle or 0 for current.
+---
--- @param method [string] Request method name
+--- Calls |vim.lsp.buf_request()| but blocks Nvim while awaiting the result.
--- @param params [string] Parameters to send to the server
+--- Parameters are the same as |vim.lsp.buf_request()| but the return result is
--- @param timeout_ms [number|100] Maximum ms to wait for a result
+--- different. Wait maximum of {timeout_ms} (default 100) ms.
---
+---
--- @returns: The table of {[client_id] = request_result}
+--@param bufnr (number) Buffer handle, or 0 for current.
+--@param method (string) LSP method name
+--@param params (optional, table) Parameters to send to the server
+--@param timeout_ms (optional, number, default=100) Maximum time in
+---      milliseconds to wait for a result.
+---
+--@returns Map of client_id:request_result. On timeout, cancel or error,
+---        returns `(nil, err)` where `err` is a string describing the failure
+---        reason.
 function lsp.buf_request_sync(bufnr, method, params, timeout_ms)
   local request_results = {}
   local result_count = 0
-  local function callback(err, _method, result, client_id)
+  local function _callback(err, _method, result, client_id)
     request_results[client_id] = { error = err, result = result }
     result_count = result_count + 1
   end
-  local client_request_ids, cancel = lsp.buf_request(bufnr, method, params, callback)
+  local client_request_ids, cancel = lsp.buf_request(bufnr, method, params, _callback)
   local expected_result_count = 0
   for _ in pairs(client_request_ids) do
     expected_result_count = expected_result_count + 1
@@ -828,12 +906,13 @@ function lsp.buf_request_sync(bufnr, method, params, timeout_ms)
   return request_results
 end
 
---- Send a notification to a server
+--- Sends a notification to all servers attached to the buffer.
--- @param bufnr [number] (optional): The number of the buffer
+---
--- @param method [string]: Name of the request method
+--@param bufnr (optional, number) Buffer handle, or 0 for current
--- @param params [string]: Arguments to send to the server
+--@param method (string) LSP method name
---
+--@param params (string) Parameters to send to the server
--- @returns nil
+---
+--@returns nil
 function lsp.buf_notify(bufnr, method, params)
   validate {
     bufnr    = { bufnr, 'n', true };
@@ -888,12 +967,10 @@ function lsp.client_is_stopped(client_id)
   return active_clients[client_id] == nil
 end
 
+--- Gets a map of client_id:client pairs for the given buffer, where each value
+--- is a |vim.lsp.client| object.
 ---
---- Miscellaneous utilities.
+--@param bufnr (optional, number): Buffer handle, or 0 for current
----
-
--- Retrieve a map from client_id to client of all active buffer clients.
--- @param bufnr [number] (optional): buffer handle or 0 for current
 function lsp.buf_get_clients(bufnr)
   bufnr = resolve_bufnr(bufnr)
  local result = {}
@@ -903,8 +980,9 @@ function lsp.buf_get_clients(bufnr)
  return result
 end
 
--- Print some debug information about the current buffer clients.
+--- Prints debug info about the current buffer clients.
--- The output of this function should not be relied upon and may change.
+---
+--- Result of this function cannot be relied upon and may change.
 function lsp.buf_print_debug_info(bufnr)
   print(vim.inspect(lsp.buf_get_clients(bufnr)))
 end
@@ -919,14 +997,20 @@ end
 --
 -- Can be used to lookup the number from the name or the
 -- name from the number.
--- Levels by name: 'trace', 'debug', 'info', 'warn', 'error'
+-- Levels by name: "trace", "debug", "info", "warn", "error"
--- Level numbers begin with 'trace' at 0
+-- Level numbers begin with "trace" at 0
 lsp.log_levels = log.levels
 
--- Set the log level for lsp logging.
+--- Sets the global log level for LSP logging.
--- Levels by name: 'trace', 'debug', 'info', 'warn', 'error'
+---
--- Level numbers begin with 'trace' at 0
+--- Levels by name: "trace", "debug", "info", "warn", "error"
--- @param level [number|string] the case insensitive level name or number @see |vim.lsp.log_levels|
+--- Level numbers begin with "trace" at 0
+---
+--- Use `lsp.log_levels` for reverse lookup.
+---
+--@see |vim.lsp.log_levels|
+---
+--@param level [number|string] the case insensitive level name or number
 function lsp.set_log_level(level)
   if type(level) == 'string' or type(level) == 'number' then
     log.set_level(level)
@@ -935,7 +1019,7 @@ function lsp.set_log_level(level)
   end
 end
 
--- Return the path of the logfile used by the LSP client.
+--- Gets the path of the logfile used by the LSP client.
 function lsp.get_log_path()
   return log.get_filename()
 end

runtime/lua/vim/lsp/protocol.lua

@@ -603,6 +603,8 @@ export interface WorkspaceClientCapabilities {
 }
 --]=]
 
+--- Gets a new ClientCapabilities object describing the LSP client
+--- capabilities.
 function protocol.make_client_capabilities()
   return {
     textDocument = {
@@ -821,6 +823,8 @@ interface ServerCapabilities {
   experimental?: any;
 }
 --]]
+
+--- Creates a normalized object describing LSP server capabilities.
 function protocol.resolve_capabilities(server_capabilities)
   local general_properties = {}
   local text_document_sync_properties

runtime/lua/vim/lsp/rpc.lua

@@ -166,9 +166,14 @@ local function format_rpc_error(err)
   return table.concat(message_parts, ' ')
 end
 
+--- Creates an RPC response object/table.
+---
+--@param code RPC error code defined in `vim.lsp.protocol.ErrorCodes`
+--@param message (optional) arbitrary message to send to server
+--@param data (optional) arbitrary data to send to server
 local function rpc_response_error(code, message, data)
   -- TODO should this error or just pick a sane error (like InternalError)?
-  local code_name = assert(protocol.ErrorCodes[code], 'Invalid rpc error code')
+  local code_name = assert(protocol.ErrorCodes[code], 'Invalid RPC error code')
   return setmetatable({
     code = code;
     message = message or code_name;

scripts/gen_vimdoc.py

@@ -55,6 +55,7 @@ if sys.version_info[0] < 3 or sys.version_info[1] < 5:
     sys.exit(1)
 
 DEBUG = ('DEBUG' in os.environ)
+TARGET = os.environ.get('TARGET', None)
 INCLUDE_C_DECL = ('INCLUDE_C_DECL' in os.environ)
 INCLUDE_DEPRECATED = ('INCLUDE_DEPRECATED' in os.environ)
 
@@ -69,6 +70,7 @@ lua2dox_filter = os.path.join(base_dir, 'scripts', 'lua2dox_filter')
 
 CONFIG = {
     'api': {
+        'mode': 'c',
         'filename': 'api.txt',
         # String used to find the start of the generated part of the doc.
         'section_start_token': '*api-global*',
@@ -85,17 +87,24 @@ CONFIG = {
         # file patterns used by doxygen
         'file_patterns': '*.h *.c',
         # Only function with this prefix are considered
-        'func_name_prefix': 'nvim_',
+        'fn_name_prefix': 'nvim_',
         # Section name overrides.
         'section_name': {
             'vim.c': 'Global',
         },
+        # For generated section names.
+        'section_fmt': lambda name: f'{name} Functions',
+        # Section helptag.
+        'helptag_fmt': lambda name: f'*api-{name.lower()}*',
+        # Per-function helptag.
+        'fn_helptag_fmt': lambda fstem, name: f'*{name}()*',
         # Module name overrides (for Lua).
         'module_override': {},
         # Append the docs for these modules, do not start a new section.
         'append_only': [],
     },
     'lua': {
+        'mode': 'lua',
         'filename': 'lua.txt',
         'section_start_token': '*lua-vim*',
         'section_order': [
@@ -107,8 +116,13 @@ CONFIG = {
             os.path.join(base_dir, 'runtime/lua/vim/shared.lua'),
         ]),
         'file_patterns': '*.lua',
-        'func_name_prefix': '',
+        'fn_name_prefix': '',
-        'section_name': {},
+        'section_name': {
+            'lsp.lua': 'core',
+        },
+        'section_fmt': lambda name: f'Lua module: {name.lower()}',
+        'helptag_fmt': lambda name: f'*lua-{name.lower()}*',
+        'fn_helptag_fmt': lambda fstem, name: f'*{fstem}.{name}()*',
         'module_override': {
             # `shared` functions are exposed on the `vim` module.
             'shared': 'vim',
@@ -117,6 +131,44 @@ CONFIG = {
             'shared.lua',
         ],
     },
+    'lsp': {
+        'mode': 'lua',
+        'filename': 'lsp.txt',
+        'section_start_token': '*lsp-core*',
+        'section_order': [
+            'lsp.lua',
+            'protocol.lua',
+            'buf.lua',
+            'callbacks.lua',
+            'log.lua',
+            'rpc.lua',
+            'util.lua'
+        ],
+        'files': ' '.join([
+            os.path.join(base_dir, 'runtime/lua/vim/lsp'),
+            os.path.join(base_dir, 'runtime/lua/vim/lsp.lua'),
+        ]),
+        'file_patterns': '*.lua',
+        'fn_name_prefix': '',
+        'section_name': {},
+        'section_fmt': lambda name: ('Lua module: vim.lsp'
+            if name.lower() == 'lsp'
+            else f'Lua module: vim.lsp.{name.lower()}'),
+        'helptag_fmt': lambda name: ('*lsp-core*'
+            if name.lower() == 'lsp'
+            else f'*lsp-{name.lower()}*'),
+        'fn_helptag_fmt': lambda fstem, name: (f'*vim.lsp.{name}()*'
+            if fstem == 'lsp' and name != 'client'
+            else ('*vim.lsp.client*'
+                # 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',
+        },
+        'append_only': [],
+    },
 }
 
 param_exclude = (
@@ -567,12 +619,12 @@ def extract_from_xml(filename, mode, width):
 
         if not fmt_vimhelp:
             pass
-        elif mode == 'lua':
-            fstem = compoundname.split('.')[0]
-            fstem = CONFIG[mode]['module_override'].get(fstem, fstem)
-            vimtag = '*{}.{}()*'.format(fstem, name)
         else:
-            vimtag = '*{}()*'.format(name)
+            fstem = '?'
+            if '.' in compoundname:
+                fstem = compoundname.split('.')[0]
+                fstem = CONFIG[mode]['module_override'].get(fstem, fstem)
+            vimtag = CONFIG[mode]['fn_helptag_fmt'](fstem, name)
 
         params = []
         type_length = 0
@@ -583,8 +635,8 @@ def extract_from_xml(filename, mode, width):
             declname = get_child(param, 'declname')
             if declname:
                 param_name = get_text(declname).strip()
-            elif mode == 'lua':
+            elif CONFIG[mode]['mode'] == 'lua':
-                # that's how it comes out of lua2dox
+                # XXX: this is what lua2dox gives us...
                 param_name = param_type
                 param_type = ''
 
@@ -614,7 +666,7 @@ def extract_from_xml(filename, mode, width):
                                      '    ')
 
             # Minimum 8 chars between signature and vimtag
-            lhs = (width - 8) - len(prefix)
+            lhs = (width - 8) - len(vimtag)
 
             if len(prefix) + len(suffix) > lhs:
                 signature = vimtag.rjust(width) + '\n'
@@ -663,7 +715,7 @@ def extract_from_xml(filename, mode, width):
 
         if 'Deprecated' in str(xrefs):
             deprecated_fns[name] = fn
-        elif name.startswith(CONFIG[mode]['func_name_prefix']):
+        elif name.startswith(CONFIG[mode]['fn_name_prefix']):
             fns[name] = fn
 
         xrefs.clear()
@@ -714,7 +766,7 @@ def fmt_doxygen_xml_as_vimhelp(filename, mode):
 
         if 'Deprecated' in xrefs:
             deprecated_fns_txt[name] = func_doc
-        elif name.startswith(CONFIG[mode]['func_name_prefix']):
+        elif name.startswith(CONFIG[mode]['fn_name_prefix']):
             fns_txt[name] = func_doc
 
         xrefs.clear()
@@ -730,9 +782,13 @@ def delete_lines_below(filename, tokenstr):
     """
     lines = open(filename).readlines()
     i = 0
+    found = False
     for i, line in enumerate(lines, 1):
         if tokenstr in line:
+            found = True
             break
+    if not found:
+        raise RuntimeError(f'not found: "{tokenstr}"')
     i = max(0, i - 2)
     with open(filename, 'wt') as fp:
         fp.writelines(lines[0:i])
@@ -747,6 +803,8 @@ def main(config):
     Doxygen is called and configured through stdin.
     """
     for mode in CONFIG:
+        if TARGET is not None and mode != TARGET:
+            continue
         mpack_file = os.path.join(
             base_dir, 'runtime', 'doc',
             CONFIG[mode]['filename'].replace('.txt', '.mpack'))
@@ -754,7 +812,10 @@ def main(config):
             os.remove(mpack_file)
 
         output_dir = out_dir.format(mode=mode)
-        p = subprocess.Popen(['doxygen', '-'], stdin=subprocess.PIPE)
+        p = subprocess.Popen(['doxygen', '-'], stdin=subprocess.PIPE,
+                # silence warnings
+                # runtime/lua/vim/lsp.lua:209: warning: argument 'trace' of command @param is not found in the argument list
+                stderr=subprocess.DEVNULL)
         p.communicate(
             config.format(
                 input=CONFIG[mode]['files'],
@@ -806,15 +867,11 @@ def main(config):
                 if not functions_text and not deprecated_text:
                     continue
                 else:
-                    name = os.path.splitext(os.path.basename(filename))[0]
+                    name = os.path.splitext(
-                    if name == 'ui':
+                            os.path.basename(filename))[0].lower()
-                        name = name.upper()
+                    sectname = name.upper() if name == 'ui' else name.title()
-                    else:
-                        name = name.title()
-
                     doc = ''
-
+                    intro = intros.get(f'api-{name}')
-                    intro = intros.get('api-%s' % name.lower())
                     if intro:
                         doc += '\n\n' + intro
 
@@ -822,33 +879,28 @@ def main(config):
                         doc += '\n\n' + functions_text
 
                     if INCLUDE_DEPRECATED and deprecated_text:
-                        doc += '\n\n\nDeprecated %s Functions: ~\n\n' % name
+                        doc += f'\n\n\nDeprecated {sectname} Functions: ~\n\n'
                         doc += deprecated_text
 
                     if doc:
                         filename = os.path.basename(filename)
-                        name = CONFIG[mode]['section_name'].get(filename, name)
+                        sectname = CONFIG[mode]['section_name'].get(
-
+                                filename, sectname)
-                        if mode == 'lua':
+                        title = CONFIG[mode]['section_fmt'](sectname)
-                            title = 'Lua module: {}'.format(name.lower())
+                        helptag = CONFIG[mode]['helptag_fmt'](sectname)
-                            helptag = '*lua-{}*'.format(name.lower())
-                        else:
-                            title = '{} Functions'.format(name)
-                            helptag = '*api-{}*'.format(name.lower())
                         sections[filename] = (title, helptag, doc)
                         fn_map_full.update(fn_map)
 
-        if not sections:
+        assert sections
-            return
+        if len(sections) > len(CONFIG[mode]['section_order']):
+            raise RuntimeError(
+                'found new modules "{}"; update the "section_order" map'.format(
+                    set(sections).difference(CONFIG[mode]['section_order'])))
 
         docs = ''
 
         i = 0
         for filename in CONFIG[mode]['section_order']:
-            if filename not in sections:
-                raise RuntimeError(
-                    'found new module "{}"; update the "section_order" map'.format(
-                        filename))
             title, helptag, section_doc = sections.pop(filename)
             i += 1
             if filename not in CONFIG[mode]['append_only']:

scripts/lua2dox.lua

@@ -17,61 +17,28 @@
 --   Free Software Foundation, Inc.,                                       --
 --   59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.             --
 ----------------------------------------------------------------------------]]
---[[!
-\file
-\brief a hack lua2dox converter
-]]
 
 --[[!
-\mainpage
+Lua-to-Doxygen converter
 
-Introduction
+Partially from lua2dox
-------------
+http://search.cpan.org/~alec/Doxygen-Lua-0.02/lib/Doxygen/Lua.pm
-
-A hack lua2dox converter
-Version 0.2
-
-This lets us make Doxygen output some documentation to let
-us develop this code.
-
-It is partially cribbed from the functionality of lua2dox
-(http://search.cpan.org/~alec/Doxygen-Lua-0.02/lib/Doxygen/Lua.pm).
-Found on CPAN when looking for something else; kinda handy.
-
-Improved from lua2dox to make the doxygen output more friendly.
-Also it runs faster in lua rather than Perl.
-
-Because this Perl based system is called "lua2dox"., I have decided to add ".lua" to the name
-to keep the two separate.
 
 Running
 -------
 
-<ol>
+This file "lua2dox.lua" gets called by "lua2dox_filter" (bash).
-<li>  Ensure doxygen is installed on your system and that you are familiar with its use.
-Best is to try to make and document some simple C/C++/PHP to see what it produces.
-You can experiment with the enclosed example code.
 
-<li> Run "doxygen -g" to create a default Doxyfile.
+Doxygen must be on your system. You can experiment like so:
 
-Then alter it to let it recognise lua. Add the two following lines:
+- Run "doxygen -g" to create a default Doxyfile.
-
+- Then alter it to let it recognise lua. Add the two following lines:
-\code{.bash}
+    FILE_PATTERNS   = *.lua
-FILE_PATTERNS   = *.lua
+    FILTER_PATTERNS = *.lua=lua2dox_filter
-
+- Then run "doxygen".
-FILTER_PATTERNS = *.lua=lua2dox_filter
-\endcode
-
-
-Either add them to the end or find the appropriate entry in Doxyfile.
-
-There are other lines that you might like to alter, but see further documentation for details.
-
-<li> When Doxyfile is edited run "doxygen"
 
 The core function reads the input file (filename or stdin) and outputs some pseudo C-ish language.
 It only has to be good enough for doxygen to see it as legal.
-Therefore our lua interpreter is fairly limited, but "good enough".
 
 One limitation is that each line is treated separately (except for long comments).
 The implication is that class and function declarations must be on the same line.
@@ -81,40 +48,8 @@ so it will probably not document accurately if we do do this.
 
 However I have put in a hack that will insert the "missing" close paren.
 The effect is that you will get the function documented, but not with the parameter list you might expect.
-</ol>
-
-Installation
-------------
-
-Here for linux or unix-like, for any other OS you need to refer to other documentation.
-
-This file is "lua2dox.lua". It gets called by "lua2dox_filter"(bash).
-Somewhere in your path (e.g. "~/bin" or "/usr/local/bin") put a link to "lua2dox_filter".
-
-Documentation
--------------
-
-Read the external documentation that should be part of this package.
-For example look for the "README" and some .PDFs.
-
 ]]
 
--- we won't use our library code, so this becomes more portable
-
--- require 'elijah_fix_require'
--- require 'elijah_class'
--- 
---! \brief ``declare'' as class
---! 
---! use as:
---! \code{.lua}
---! TWibble = class()
---! function TWibble.init(this,Str)
---! 	this.str = Str
---! 	-- more stuff here
---! end
---! \endcode
---! 
 function class(BaseClass, ClassInitialiser)
   local newClass = {}    -- a new class newClass
   if not ClassInitialiser and type(BaseClass) == 'function' then
@@ -165,8 +100,6 @@ function class(BaseClass, ClassInitialiser)
   return newClass
 end
 
--- require 'elijah_clock'
-
 --! \class TCore_Clock
 --! \brief a clock
 TCore_Clock = class()
@@ -201,9 +134,6 @@ function TCore_Clock.getTimeStamp(this,T0)
 end
 
 
---require 'elijah_io'
-
---! \class TCore_IO
 --! \brief io to console
 --! 
 --! pseudo class (no methods, just to keep documentation tidy)
@@ -225,8 +155,6 @@ function TCore_IO_writeln(Str)
 end
 
 
---require 'elijah_string'
-
 --! \brief trims a string
 function string_trim(Str)
   return Str:match("^%s*(.-)%s*$")
@@ -257,8 +185,6 @@ function string_split(Str, Pattern)
 end
 
 
---require 'elijah_commandline'
-
 --! \class TCore_Commandline
 --! \brief reads/parses commandline
 TCore_Commandline = class()
@@ -279,9 +205,6 @@ function TCore_Commandline.getRaw(this,Key,Default)
   return val
 end
 
-
---require 'elijah_debug'
-
 -------------------------------
 --! \brief file buffer
 --!