Merge pull request #17707 from tesaguri/refactor-gen_vimdoc

6 files changed, 125 insertions, 127 deletions

diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index 9c3c143045..4af13a3bbf 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -594,7 +594,8 @@ nvim__id_float({flt})                                       *nvim__id_float()*
                     its argument.
 
 nvim__inspect_cell({grid}, {row}, {col})                *nvim__inspect_cell()*
-                TODO: Documentation
+                NB: if your UI doesn't use hlstate, this will not return
+                hlstate first time.
 
 nvim__runtime_inspect()                              *nvim__runtime_inspect()*
                 TODO: Documentation
@@ -709,7 +710,7 @@ nvim_call_atomic({calls})                                 *nvim_call_atomic()*
                     be returned.
 
 nvim_chan_send({chan}, {data})                              *nvim_chan_send()*
-                Send data to channel `id` . For a job, it writes it to the
+                Send data to channel `id`. For a job, it writes it to the
                 stdin of the process. For the stdio channel |channel-stdio|,
                 it writes to Nvim's stdout. For an internal terminal instance
                 (|nvim_open_term()|) it writes directly to terminal output.
@@ -849,7 +850,7 @@ nvim_exec_lua({code}, {args})                                *nvim_exec_lua()*
                 inside the chunk. The chunk can return a value.
 
                 Only statements are executed. To evaluate an expression,
-                prefix it with `return` : return my_function(...)
+                prefix it with `return`: return my_function(...)
 
                 Parameters: ~
                     {code}  Lua code to execute
@@ -1132,13 +1133,13 @@ nvim_get_option_value({name}, {*opts})               *nvim_get_option_value()*
                     Option value
 
 nvim_get_proc({pid})                                         *nvim_get_proc()*
-                Gets info describing process `pid` .
+                Gets info describing process `pid`.
 
                 Return: ~
                     Map of process properties, or NIL if process not found.
 
 nvim_get_proc_children({pid})                       *nvim_get_proc_children()*
-                Gets the immediate children of process `pid` .
+                Gets the immediate children of process `pid`.
 
                 Return: ~
                     Array of child process ids, empty if process not found.
@@ -1247,8 +1248,8 @@ nvim_input_mouse({button}, {action}, {modifier}, {grid}, {row}, {col})
 nvim_list_bufs()                                            *nvim_list_bufs()*
                 Gets the current list of buffer handles
 
-                Includes unlisted (unloaded/deleted) buffers, like `:ls!` .
-                Use |nvim_buf_is_loaded()| to check if a buffer is loaded.
+                Includes unlisted (unloaded/deleted) buffers, like `:ls!`. Use
+                |nvim_buf_is_loaded()| to check if a buffer is loaded.
 
                 Return: ~
                     List of buffer handles
@@ -1357,7 +1358,7 @@ nvim_paste({data}, {crlf}, {phase})                             *nvim_paste()*
 
                 Errors ('nomodifiable', `vim.paste()` failure, …) are
                 reflected in `err` but do not affect the return value (which
-                is strictly decided by `vim.paste()` ). On error, subsequent
+                is strictly decided by `vim.paste()`). On error, subsequent
                 calls are ignored ("drained") until the next paste is
                 initiated (phase 1 or -1).
 
@@ -1434,7 +1435,7 @@ nvim_select_popupmenu_item({item}, {insert}, {finish}, {opts})
                     {insert}  Whether the selection should be inserted in the
                               buffer.
                     {finish}  Finish the completion and dismiss the popupmenu.
-                              Implies `insert` .
+                              Implies `insert`.
                     {opts}    Optional parameters. Reserved for future use.
 
                                                       *nvim_set_client_info()*
@@ -1547,18 +1548,21 @@ nvim_set_hl({ns_id}, {name}, {*val})                           *nvim_set_hl()*
                 Sets a highlight group.
 
                 Parameters: ~
-                    {ns_id}  Namespace id for this highlight |nvim_create_namespace()|.
-                             Use 0 to set a highlight group globally |:highlight|.
+                    {ns_id}  Namespace id for this highlight
+                             |nvim_create_namespace()|. Use 0 to set a
+                             highlight group globally |:highlight|.
                     {name}   Highlight group name, e.g. "ErrorMsg"
                     {val}    Highlight definition map, like |synIDattr()|. In
                              addition, the following keys are recognized:
-                             • default: Don't override existing definition |:hi-default|
-                             • ctermfg: Sets foreground of cterm color |highlight-ctermfg|
-                             • ctermbg: Sets background of cterm color |highlight-ctermbg|
+                             • default: Don't override existing definition
+                               |:hi-default|
+                             • ctermfg: Sets foreground of cterm color
+                               |highlight-ctermfg|
+                             • ctermbg: Sets background of cterm color
+                               |highlight-ctermbg|
                              • cterm: cterm attribute map, like
-                               |highlight-args|.
-                               Note: Attributes default to those set for `gui`
-                                     if not set.
+                               |highlight-args|. Note: Attributes default to
+                               those set for `gui` if not set.
 
 nvim_set_keymap({mode}, {lhs}, {rhs}, {*opts})             *nvim_set_keymap()*
                 Sets a global |mapping| for the given mode.
@@ -1627,7 +1631,7 @@ nvim_set_vvar({name}, {value})                               *nvim_set_vvar()*
                     {value}  Variable value
 
 nvim_strwidth({text})                                        *nvim_strwidth()*
-                Calculates the number of display cells occupied by `text` .
+                Calculates the number of display cells occupied by `text`.
                 <Tab> counts as one cell.
 
                 Parameters: ~
@@ -1879,9 +1883,10 @@ nvim_buf_attach({buffer}, {send_buffer}, {opts})           *nvim_buf_attach()*
                     {buffer}       Buffer handle, or 0 for current buffer
                     {send_buffer}  True if the initial notification should
                                    contain the whole buffer: first
-                                   notification will be `nvim_buf_lines_event`
-                                   . Else the first notification will be
-                                   `nvim_buf_changedtick_event` . Not for Lua
+                                   notification will be
+                                   `nvim_buf_lines_event`. Else the first
+                                   notification will be
+                                   `nvim_buf_changedtick_event`. Not for Lua
                                    callbacks.
                     {opts}         Optional parameters.
                                    • on_lines: Lua callback invoked on change.
@@ -1937,7 +1942,7 @@ nvim_buf_attach({buffer}, {send_buffer}, {opts})           *nvim_buf_attach()*
 
                                    • utf_sizes: include UTF-32 and UTF-16 size
                                      of the replaced region, as args to
-                                     `on_lines` .
+                                     `on_lines`.
                                    • preview: also attach to command preview
                                      (i.e. 'inccommand') events.
 
@@ -2352,7 +2357,7 @@ nvim_buf_add_highlight({buffer}, {ns_id}, {hl_group}, {line}, {col_start},
                 namespace. All highlights in the same namespace can then be
                 cleared with single call to |nvim_buf_clear_namespace()|. If
                 the highlight never will be deleted by an API call, pass
-                `ns_id = -1` .
+                `ns_id = -1`.
 
                 As a shorthand, `ns_id = 0` can be used to create a new
                 namespace for the highlight, the allocated id is then
@@ -2432,8 +2437,8 @@ nvim_buf_get_extmarks({buffer}, {ns_id}, {start}, {end}, {opts})
     nvim_buf_get_extmarks(0, my_ns, [0,0], [-1,-1], {})
 <
 
-                If `end` is less than `start` , traversal works backwards.
-                (Useful with `limit` , to get the first marks prior to a given
+                If `end` is less than `start`, traversal works backwards.
+                (Useful with `limit`, to get the first marks prior to a given
                 position.)
 
                 Example:
@@ -2780,7 +2785,7 @@ nvim_win_hide({window})                                      *nvim_win_hide()*
                 |:hide| with a |window-ID|).
 
                 Like |:hide| the buffer becomes hidden unless another window
-                is editing it, or 'bufhidden' is `unload` , `delete` or `wipe`
+                is editing it, or 'bufhidden' is `unload`, `delete` or `wipe`
                 as opposed to |:close| or |nvim_win_close|, which will close
                 the buffer.
 
@@ -3028,7 +3033,7 @@ nvim_win_set_config({window}, {*config})               *nvim_win_set_config()*
                 layouts).
 
                 When reconfiguring a floating window, absent option keys will
-                not be changed. `row` / `col` and `relative` must be
+                not be changed. `row`/`col` and `relative` must be
                 reconfigured together.
 
                 Parameters: ~
diff --git a/runtime/doc/diagnostic.txt b/runtime/doc/diagnostic.txt
index e33c786482..32936a7ee6 100644
--- a/runtime/doc/diagnostic.txt
+++ b/runtime/doc/diagnostic.txt
@@ -328,11 +328,11 @@ config({opts}, {namespace})                          *vim.diagnostic.config()*
                 Note:
                     Each of the configuration options below accepts one of the
                     following:
-                    • `false` : Disable this feature
-                    • `true` : Enable this feature, use default settings.
-                    • `table` : Enable this feature with overrides. Use an
+                    • `false`: Disable this feature
+                    • `true`: Enable this feature, use default settings.
+                    • `table`: Enable this feature with overrides. Use an
                       empty table to use default values.
-                    • `function` : Function with signature (namespace, bufnr)
+                    • `function`: Function with signature (namespace, bufnr)
                       that returns any of the above.
 
                 Parameters: ~
diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt
index 54c648e171..a9ebcd27ae 100644
--- a/runtime/doc/lsp.txt
+++ b/runtime/doc/lsp.txt
@@ -563,7 +563,7 @@ buf_request_all({bufnr}, {method}, {params}, {callback})
 
                 Return: ~
                     (function) A function that will cancel all requests which
-                    is the same as the one returned from `buf_request` .
+                    is the same as the one returned from `buf_request`.
 
                                                   *vim.lsp.buf_request_sync()*
 buf_request_sync({bufnr}, {method}, {params}, {timeout_ms})
@@ -600,9 +600,9 @@ client()                                                      *vim.lsp.client*
                     {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
+                    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
+                    {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
@@ -612,13 +612,13 @@ client()                                                      *vim.lsp.client*
                     `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` .
+                    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()` .
+                    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
@@ -639,14 +639,14 @@ client()                                                      *vim.lsp.client*
                     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
+                    `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|.
                   • {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
+                    `type`, `bufnr`, and `method` key-value pairs. `type` is
                     either "pending" for an active request, or "cancel" for a
                     cancel request.
                   • {config} (table): copy of the table that was passed by the
@@ -655,7 +655,7 @@ client()                                                      *vim.lsp.client*
                     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` .
+                    response from the server in `server_capabilities`.
 
 client_is_stopped({client_id})                   *vim.lsp.client_is_stopped()*
                 Checks whether a client is stopped.
@@ -775,7 +775,7 @@ start_client({config})                                *vim.lsp.start_client()*
                                          initiates the LSP client.
                     {cmd_cwd}            (string, default=|getcwd()|)
                                          Directory to launch the `cmd`
-                                         process. Not related to `root_dir` .
+                                         process. Not related to `root_dir`.
                     {cmd_env}            (table) Environment flags to pass to
                                          the LSP on spawn. Can be specified
                                          using keys like a map or as a list
@@ -800,15 +800,15 @@ start_client({config})                                *vim.lsp.start_client()*
                                          its result.
                                          • Note: To send an empty dictionary
                                            use
-                                           `{[vim.type_idx]=vim.types.dictionary}`
-                                           , else it will be encoded as an
+                                           `{[vim.type_idx]=vim.types.dictionary}`,
+                                           else it will be encoded as an
                                            array.
                     {handlers}           Map of language server method names
                                          to |lsp-handler|
                     {settings}           Map with language server specific
                                          settings. These are returned to the
                                          language server if requested via
-                                         `workspace/configuration` . Keys are
+                                         `workspace/configuration`. Keys are
                                          case-sensitive.
                     {commands}           table Table that maps string of
                                          clientside commands to user-defined
@@ -821,7 +821,7 @@ start_client({config})                                *vim.lsp.start_client()*
                                          action, code lenses, ...) triggers
                                          the command.
                     {init_options}       Values to pass in the initialization
-                                         request as `initializationOptions` .
+                                         request as `initializationOptions`.
                                          See `initialize` in the LSP spec.
                     {name}               (string, default=client-id) Name in
                                          log messages.
@@ -976,7 +976,7 @@ code_action({context})                             *vim.lsp.buf.code_action()*
                                • only: (string|nil) LSP `CodeActionKind` used
                                  to filter the code actions. Most language
                                  servers support values like `refactor` or
-                                 `quickfix` .
+                                 `quickfix`.
 
                 See also: ~
                     https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_codeAction
@@ -1007,7 +1007,7 @@ definition()                                        *vim.lsp.buf.definition()*
 document_highlight()                        *vim.lsp.buf.document_highlight()*
                 Send request to the server to resolve document highlights for
                 the current text document position. This request can be
-                triggered by a key mapping or by events such as `CursorHold` ,
+                triggered by a key mapping or by events such as `CursorHold`,
                 e.g.:
 >
     autocmd CursorHold  <buffer> lua vim.lsp.buf.document_highlight()
@@ -1124,7 +1124,7 @@ range_code_action({context}, {start_pos}, {end_pos})
                                  • only: (string|nil) LSP `CodeActionKind`
                                    used to filter the code actions. Most
                                    language servers support values like
-                                   `refactor` or `quickfix` .
+                                   `refactor` or `quickfix`.
                     {start_pos}  ({number, number}, optional) mark-indexed
                                  position. Defaults to the start of the last
                                  visual selection.
@@ -1246,8 +1246,8 @@ display({lenses}, {bufnr}, {client_id})           *vim.lsp.codelens.display()*
                 Display the lenses using virtual text
 
                 Parameters: ~
-                    {lenses}     table of lenses to display ( `CodeLens[] |
-                                 null` )
+                    {lenses}     table of lenses to display (`CodeLens[] |
+                                 null`)
                     {bufnr}      number
                     {client_id}  number
 
@@ -1259,7 +1259,7 @@ get({bufnr})                                          *vim.lsp.codelens.get()*
                              current buffer.
 
                 Return: ~
-                    table ( `CodeLens[]` )
+                    table (`CodeLens[]`)
 
                                               *vim.lsp.codelens.on_codelens()*
 on_codelens({err}, {result}, {ctx}, {_})
@@ -1281,8 +1281,8 @@ save({lenses}, {bufnr}, {client_id})                 *vim.lsp.codelens.save()*
                 Store lenses for a specific buffer and client
 
                 Parameters: ~
-                    {lenses}     table of lenses to store ( `CodeLens[] |
-                                 null` )
+                    {lenses}     table of lenses to store (`CodeLens[] |
+                                 null`)
                     {bufnr}      number
                     {client_id}  number
 
@@ -1333,7 +1333,7 @@ Lua module: vim.lsp.util                                            *lsp-util*
 
                                      *vim.lsp.util.apply_text_document_edit()*
 apply_text_document_edit({text_document_edit}, {index}, {offset_encoding})
-                Applies a `TextDocumentEdit` , which is a list of changes to a
+                Applies a `TextDocumentEdit`, which is a list of changes to a
                 single document.
 
                 Parameters: ~
@@ -1360,7 +1360,7 @@ apply_text_edits({text_edits}, {bufnr}, {offset_encoding})
 
                                          *vim.lsp.util.apply_workspace_edit()*
 apply_workspace_edit({workspace_edit}, {offset_encoding})
-                Applies a `WorkspaceEdit` .
+                Applies a `WorkspaceEdit`.
 
                 Parameters: ~
                     {workspace_edit}   table `WorkspaceEdit`
@@ -1408,13 +1408,13 @@ convert_input_to_markdown_lines({input}, {contents})
                 Converts any of `MarkedString` | `MarkedString[]` |
                 `MarkupContent` into a list of lines containing valid
                 markdown. Useful to populate the hover window for
-                `textDocument/hover` , for parsing the result of
-                `textDocument/signatureHelp` , and potentially others.
+                `textDocument/hover`, for parsing the result of
+                `textDocument/signatureHelp`, and potentially others.
 
                 Parameters: ~
-                    {input}     ( `MarkedString` | `MarkedString[]` |
-                                `MarkupContent` )
-                    {contents}  (table, optional, default `{}` ) List of
+                    {input}     (`MarkedString` | `MarkedString[]` |
+                                `MarkupContent`)
+                    {contents}  (table, optional, default `{}`) List of
                                 strings to extend with converted lines
 
                 Return: ~
@@ -1475,7 +1475,7 @@ jump_to_location({location}, {offset_encoding})
                 Jumps to a location.
 
                 Parameters: ~
-                    {location}         table ( `Location` | `LocationLink` )
+                    {location}         table (`Location`|`LocationLink`)
                     {offset_encoding}  string utf-8|utf-16|utf-32 (required)
 
                 Return: ~
@@ -1491,8 +1491,8 @@ locations_to_items({locations}, {offset_encoding})
                 |setqflist()| or |setloclist()|.
 
                 Parameters: ~
-                    {locations}        table list of `Location` s or
-                                       `LocationLink` s
+                    {locations}        table list of `Location`s or
+                                       `LocationLink`s
                     {offset_encoding}  string offset_encoding for locations
                                        utf-8|utf-16|utf-32
 
@@ -1526,7 +1526,7 @@ make_floating_popup_options({width}, {height}, {opts})
                               • border (string or table) override `border`
                               • focusable (string or table) override
                                 `focusable`
-                              • zindex (string or table) override `zindex` ,
+                              • zindex (string or table) override `zindex`,
                                 defaults to 50
 
                 Return: ~
@@ -1566,7 +1566,7 @@ make_given_range_params({start_pos}, {end_pos}, {bufnr}, {offset_encoding})
 
                 Return: ~
                     { textDocument = { uri = `current_file_uri` }, range = {
-                    start = `start_position` , end = `end_position` } }
+                    start = `start_position`, end = `end_position` } }
 
                                          *vim.lsp.util.make_position_params()*
 make_position_params({window}, {offset_encoding})
@@ -1590,9 +1590,9 @@ make_position_params({window}, {offset_encoding})
 make_range_params({window}, {offset_encoding})
                 Using the current position in the current buffer, creates an
                 object that can be used as a building block for several LSP
-                requests, such as `textDocument/codeAction` ,
-                `textDocument/colorPresentation` ,
-                `textDocument/rangeFormatting` .
+                requests, such as `textDocument/codeAction`,
+                `textDocument/colorPresentation`,
+                `textDocument/rangeFormatting`.
 
                 Parameters: ~
                     {window}           (optional, number): window handle or 0
@@ -1603,7 +1603,7 @@ make_range_params({window}, {offset_encoding})
 
                 Return: ~
                     { textDocument = { uri = `current_file_uri` }, range = {
-                    start = `current_position` , end = `current_position` } }
+                    start = `current_position`, end = `current_position` } }
 
                                     *vim.lsp.util.make_text_document_params()*
 make_text_document_params({bufnr})
@@ -1657,8 +1657,8 @@ open_floating_preview({contents}, {syntax}, {opts})
                                   closes the floating window
                                 • focusable: (boolean, default true) Make
                                   float focusable
-                                • focus: (boolean, default true) If `true` ,
-                                  and if {focusable} is also `true` , focus an
+                                • focus: (boolean, default true) If `true`,
+                                  and if {focusable} is also `true`, focus an
                                   existing floating window with the same
                                   {focus_id}
 
@@ -1757,7 +1757,7 @@ text_document_completion_list_to_complete_items({result}, {prefix})
                 Parameters: ~
                     {result}  The result of a `textDocument/completion` call,
                               e.g. from |vim.lsp.buf.completion()|, which may
-                              be one of `CompletionItem[]` , `CompletionList`
+                              be one of `CompletionItem[]`, `CompletionList`
                               or `null`
                     {prefix}  (string) the prefix to filter the completion
                               items
diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index 11629332ae..93386ddfe9 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -1418,7 +1418,7 @@ deep_equal({a}, {b})                                        *vim.deep_equal()*
                     {b}  second value
 
                 Return: ~
-                    `true` if values are equals, else `false` .
+                    `true` if values are equals, else `false`.
 
 deepcopy({orig})                                              *vim.deepcopy()*
                 Returns a deep copy of the given object. Non-table objects are
@@ -1435,7 +1435,7 @@ deepcopy({orig})                                              *vim.deepcopy()*
                     New table of copied keys and (nested) values.
 
 endswith({s}, {suffix})                                       *vim.endswith()*
-                Tests if `s` ends with `suffix` .
+                Tests if `s` ends with `suffix`.
 
                 Parameters: ~
                     {s}       (string) a string
@@ -1539,7 +1539,7 @@ split({s}, {sep}, {kwargs})                                      *vim.split()*
                     |vim.gsplit()|
 
 startswith({s}, {prefix})                                   *vim.startswith()*
-                Tests if `s` starts with `prefix` .
+                Tests if `s` starts with `prefix`.
 
                 Parameters: ~
                     {s}       (string) a string
@@ -1556,7 +1556,7 @@ tbl_add_reverse_lookup({o})                     *vim.tbl_add_reverse_lookup()*
                     {o}  table The table to add the reverse to.
 
 tbl_contains({t}, {value})                                *vim.tbl_contains()*
-                Checks if a list-like (vector) table contains `value` .
+                Checks if a list-like (vector) table contains `value`.
 
                 Parameters: ~
                     {t}      Table to check
@@ -1566,7 +1566,7 @@ tbl_contains({t}, {value})                                *vim.tbl_contains()*
                     true if `t` contains `value`
 
 tbl_count({t})                                               *vim.tbl_count()*
-                Counts the number of non-nil values in table `t` .
+                Counts the number of non-nil values in table `t`.
 >
 
     vim.tbl_count({ a=1, b=2 }) => 2
@@ -1651,7 +1651,7 @@ tbl_islist({t})                                             *vim.tbl_islist()*
                     {t}  Table
 
                 Return: ~
-                    `true` if array-like table, else `false` .
+                    `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
@@ -1813,7 +1813,7 @@ input({opts}, {on_confirm})                                   *vim.ui.input()*
                 Parameters: ~
                     {opts}        table Additional options. See |input()|
                                   • prompt (string|nil) Text of the prompt.
-                                    Defaults to `Input:` .
+                                    Defaults to `Input:`.
                                   • default (string|nil) Default reply to the
                                     input
                                   • completion (string|nil) Specifies type of
@@ -1856,16 +1856,16 @@ select({items}, {opts}, {on_choice})                         *vim.ui.select()*
                                    Defaults to `Select one of:`
                                  • format_item (function item -> text)
                                    Function to format an individual item from
-                                   `items` . Defaults to `tostring` .
+                                   `items`. Defaults to `tostring`.
                                  • kind (string|nil) Arbitrary hint string
                                    indicating the item shape. Plugins
                                    reimplementing `vim.ui.select` may wish to
                                    use this to infer the structure or
-                                   semantics of `items` , or the context in
+                                   semantics of `items`, or the context in
                                    which select() was called.
                     {on_choice}  function ((item|nil, idx|nil) -> ()) Called
                                  once the user made a choice. `idx` is the
-                                 1-based index of `item` within `item` . `nil`
+                                 1-based index of `item` within `item`. `nil`
                                  if the user aborted the dialog.
 
 
@@ -1990,9 +1990,9 @@ set({mode}, {lhs}, {rhs}, {opts})                           *vim.keymap.set()*
                     vim.keymap.set('n', 'asdf', require('jkl').my_fun)
 <
 
-                the require('jkl') gets evaluated during this call in order to
-                access the function. If you want to avoid this cost at startup
-                you can wrap it in a function, for example: >
+                the require('jkl )` gets evaluated during this call in order to access the
+                function. If you want to avoid this cost at startup you can
+                wrap it in a function, for example: >
 
                     vim.keymap.set('n', 'asdf', function() return require('jkl').my_fun() end)
 <
@@ -2014,7 +2014,7 @@ set({mode}, {lhs}, {rhs}, {opts})                           *vim.keymap.set()*
                               result of Lua expr maps.
                             • remap: (boolean) Make the mapping recursive.
                               This is the inverse of the "noremap" option from
-                              |nvim_set_keymap()|. Default `false` .
+                              |nvim_set_keymap()|. Default `false`.
 
                 See also: ~
                     |nvim_set_keymap()|
diff --git a/runtime/doc/treesitter.txt b/runtime/doc/treesitter.txt
index 02be20c5e8..a9d9f81849 100644
--- a/runtime/doc/treesitter.txt
+++ b/runtime/doc/treesitter.txt
@@ -468,7 +468,7 @@ parse_query({lang}, {query})                                   *parse_query()*
 
                 Exposes `info` and `captures` with additional context about {query}.
                 • `captures` contains the list of unique capture names defined
-                  in {query}. - `info.captures` also points to `captures` .
+                  in {query}. -`info.captures` also points to `captures`.
                 • `info.patterns` contains information about predicates.
 
                 Parameters: ~
@@ -528,8 +528,8 @@ Query:iter_matches({self}, {node}, {source}, {start}, {stop})
                 a table mapping capture indices to nodes, and metadata from
                 any directives processing the match. If the query has more
                 than one pattern the capture table might be sparse, and e.g.
-                `pairs()` method should be used over `ipairs` . Here an
-                example iterating over all captures in every match:
+                `pairs()` method should be used over `ipairs`. Here an example
+                iterating over all captures in every match:
 >
 
     for pattern, match, metadata in cquery:iter_matches(tree:root(), bufnr, first, last) do
diff --git a/scripts/gen_vimdoc.py b/scripts/gen_vimdoc.py
index af49d57492..7152f1005f 100755
--- a/scripts/gen_vimdoc.py
+++ b/scripts/gen_vimdoc.py
@@ -84,8 +84,6 @@ 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*',
         # Section ordering.
         'section_order': [
             'vim.c',
@@ -98,8 +96,8 @@ CONFIG = {
             'autocmd.c',
             'ui.c',
         ],
-        # List of files/directories for doxygen to read, separated by blanks
-        'files': os.path.join(base_dir, 'src/nvim/api'),
+        # List of files/directories for doxygen to read, relative to `base_dir`
+        'files': ['src/nvim/api'],
         # file patterns used by doxygen
         'file_patterns': '*.h *.c',
         # Only function with this prefix are considered
@@ -122,7 +120,6 @@ CONFIG = {
     'lua': {
         'mode': 'lua',
         'filename': 'lua.txt',
-        'section_start_token': '*lua-vim*',
         'section_order': [
             '_editor.lua',
             'shared.lua',
@@ -131,14 +128,14 @@ CONFIG = {
             'filetype.lua',
             'keymap.lua',
         ],
-        'files': ' '.join([
-            os.path.join(base_dir, 'runtime/lua/vim/_editor.lua'),
-            os.path.join(base_dir, 'runtime/lua/vim/shared.lua'),
-            os.path.join(base_dir, 'runtime/lua/vim/uri.lua'),
-            os.path.join(base_dir, 'runtime/lua/vim/ui.lua'),
-            os.path.join(base_dir, 'runtime/lua/vim/filetype.lua'),
-            os.path.join(base_dir, 'runtime/lua/vim/keymap.lua'),
-        ]),
+        'files': [
+            'runtime/lua/vim/_editor.lua',
+            'runtime/lua/vim/shared.lua',
+            'runtime/lua/vim/uri.lua',
+            'runtime/lua/vim/ui.lua',
+            'runtime/lua/vim/filetype.lua',
+            'runtime/lua/vim/keymap.lua',
+        ],
         'file_patterns': '*.lua',
         'fn_name_prefix': '',
         'section_name': {
@@ -171,7 +168,6 @@ CONFIG = {
     'lsp': {
         'mode': 'lua',
         'filename': 'lsp.txt',
-        'section_start_token': '*lsp-core*',
         'section_order': [
             'lsp.lua',
             'buf.lua',
@@ -185,10 +181,10 @@ CONFIG = {
             'sync.lua',
             'protocol.lua',
         ],
-        'files': ' '.join([
-            os.path.join(base_dir, 'runtime/lua/vim/lsp'),
-            os.path.join(base_dir, 'runtime/lua/vim/lsp.lua'),
-        ]),
+        'files': [
+            'runtime/lua/vim/lsp',
+            'runtime/lua/vim/lsp.lua',
+        ],
         'file_patterns': '*.lua',
         'fn_name_prefix': '',
         'section_name': {'lsp.lua': 'lsp'},
@@ -214,11 +210,10 @@ CONFIG = {
     'diagnostic': {
         'mode': 'lua',
         'filename': 'diagnostic.txt',
-        'section_start_token': '*diagnostic-api*',
         'section_order': [
             'diagnostic.lua',
         ],
-        'files': os.path.join(base_dir, 'runtime/lua/vim/diagnostic.lua'),
+        'files': ['runtime/lua/vim/diagnostic.lua'],
         'file_patterns': '*.lua',
         'fn_name_prefix': '',
         'section_name': {'diagnostic.lua': 'diagnostic'},
@@ -231,7 +226,6 @@ CONFIG = {
     'treesitter': {
         'mode': 'lua',
         'filename': 'treesitter.txt',
-        'section_start_token': '*lua-treesitter-core*',
         'section_order': [
             'treesitter.lua',
             'language.lua',
@@ -239,10 +233,10 @@ CONFIG = {
             'highlighter.lua',
             'languagetree.lua',
         ],
-        'files': ' '.join([
-            os.path.join(base_dir, 'runtime/lua/vim/treesitter.lua'),
-            os.path.join(base_dir, 'runtime/lua/vim/treesitter/'),
-        ]),
+        'files': [
+            'runtime/lua/vim/treesitter.lua',
+            'runtime/lua/vim/treesitter/',
+        ],
         'file_patterns': '*.lua',
         'fn_name_prefix': '',
         'section_name': {},
@@ -349,14 +343,6 @@ def self_or_child(n):
     return n.childNodes[0]
 
 
-def clean_text(text):
-    """Cleans text.
-
-    Only cleans superfluous whitespace at the moment.
-    """
-    return ' '.join(text.split()).strip()
-
-
 def clean_lines(text):
     """Removes superfluous lines.
 
@@ -377,12 +363,12 @@ def get_text(n, preformatted=False):
     if n.nodeName == 'computeroutput':
         for node in n.childNodes:
             text += get_text(node)
-        return '`{}` '.format(text)
+        return '`{}`'.format(text)
     for node in n.childNodes:
         if node.nodeType == node.TEXT_NODE:
-            text += node.data if preformatted else clean_text(node.data)
+            text += node.data
         elif node.nodeType == node.ELEMENT_NODE:
-            text += ' ' + get_text(node, preformatted)
+            text += get_text(node, preformatted)
     return text
 
 
@@ -849,7 +835,9 @@ def extract_from_xml(filename, target, width):
             'seealso': [],
         }
         if fmt_vimhelp:
-            fn['desc_node'] = desc  # HACK :(
+            # HACK :(
+            fn['desc_node'] = desc
+            fn['brief_desc_node'] = brief_desc
 
         for m in paras:
             if 'text' in m:
@@ -897,6 +885,8 @@ def fmt_doxygen_xml_as_vimhelp(filename, target):
         # Generate Vim :help for parameters.
         if fn['desc_node']:
             doc = fmt_node_as_vimhelp(fn['desc_node'])
+        if not doc and fn['brief_desc_node']:
+            doc = fmt_node_as_vimhelp(fn['brief_desc_node'])
         if not doc:
             doc = 'TODO: Documentation'
 
@@ -1006,7 +996,8 @@ def main(config, args):
                 stderr=(subprocess.STDOUT if debug else subprocess.DEVNULL))
         p.communicate(
             config.format(
-                input=CONFIG[target]['files'],
+                input=' '.join(
+                    [f'"{file}"' for file in CONFIG[target]['files']]),
                 output=output_dir,
                 filter=filter_cmd,
                 file_patterns=CONFIG[target]['file_patterns'])
@@ -1096,6 +1087,7 @@ def main(config, args):
             raise RuntimeError(
                 'found new modules "{}"; update the "section_order" map'.format(
                     set(sections).difference(CONFIG[target]['section_order'])))
+        first_section_tag = sections[CONFIG[target]['section_order'][0]][1]
 
         docs = ''
 
@@ -1121,7 +1113,8 @@ def main(config, args):
         doc_file = os.path.join(base_dir, 'runtime', 'doc',
                                 CONFIG[target]['filename'])
 
-        delete_lines_below(doc_file, CONFIG[target]['section_start_token'])
+        if os.path.exists(doc_file):
+            delete_lines_below(doc_file, first_section_tag)
         with open(doc_file, 'ab') as fp:
             fp.write(docs.encode('utf8'))