docs: support inline markdown

- Tags are now created with `[tag]()`
- References are now created with `[tag]`
- Code spans are no longer wrapped

6 files changed, 137 insertions, 131 deletions

diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index 1b00777532..87269ad147 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -770,9 +770,9 @@ nvim_echo({chunks}, {history}, {opts})                           *nvim_echo()*
     Echo a message.
 
     Parameters: ~
-      • {chunks}   A list of [text, hl_group] arrays, each representing a text
-                   chunk with specified highlight. `hl_group` element can be
-                   omitted for no highlight.
+      • {chunks}   A list of `[text, hl_group]` arrays, each representing a
+                   text chunk with specified highlight. `hl_group` element can
+                   be omitted for no highlight.
       • {history}  if true, add to |message-history|.
       • {opts}     Optional parameters.
                    • verbose: Message was printed as a result of 'verbose'
@@ -883,7 +883,7 @@ nvim_get_api_info()                                      *nvim_get_api_info()*
         |RPC| only
 
     Return: ~
-        2-tuple [{channel-id}, {api-metadata}]
+        2-tuple `[{channel-id}, {api-metadata}]`
 
 nvim_get_chan_info({chan})                              *nvim_get_chan_info()*
     Gets information about a channel.
@@ -1115,7 +1115,7 @@ nvim_input({keys})                                              *nvim_input()*
       • |keycodes| like <CR> are translated, so "<" is special. To input a
         literal "<", send <LT>.
       • For mouse events use |nvim_input_mouse()|. The pseudokey form
-        "<LeftMouse><col,row>" is deprecated since |api-level| 6.
+        `<LeftMouse><col,row>` is deprecated since |api-level| 6.
 
     Attributes: ~
         |api-fast|
@@ -1138,7 +1138,7 @@ nvim_input_mouse({button}, {action}, {modifier}, {grid}, {row}, {col})
       • Currently this doesn't support "scripting" multiple mouse events by
         calling it multiple times in a loop: the intermediate mouse positions
         will be ignored. It should be used to implement real-time mouse input
-        in a GUI. The deprecated pseudokey form ("<LeftMouse><col,row>") of
+        in a GUI. The deprecated pseudokey form (`<LeftMouse><col,row>`) of
         |nvim_input()| has the same limitation.
 
     Attributes: ~
@@ -1246,7 +1246,7 @@ nvim_open_term({buffer}, {opts})                            *nvim_open_term()*
                     be to the pty master end. For instance, a carriage return
                     is sent as a "\r", not as a "\n". |textlock| applies. It
                     is possible to call |nvim_chan_send()| directly in the
-                    callback however. ["input", term, bufnr, data]
+                    callback however. `["input", term, bufnr, data]`
                   • force_crlf: (boolean, default true) Convert "\n" to
                     "\r\n".
 
@@ -1523,7 +1523,7 @@ nvim_set_keymap({mode}, {lhs}, {rhs}, {opts})              *nvim_set_keymap()*
     To set a buffer-local mapping, use |nvim_buf_set_keymap()|.
 
     Unlike |:map|, leading/trailing whitespace is accepted as part of the
-    {lhs} or {rhs}. Empty {rhs} is |<Nop>|. |keycodes| are replaced as usual.
+    {lhs} or {rhs}. Empty {rhs} is <Nop>. |keycodes| are replaced as usual.
 
     Example: >vim
         call nvim_set_keymap('n', ' <NL>', '', {'nowait': v:true})
@@ -1541,7 +1541,7 @@ nvim_set_keymap({mode}, {lhs}, {rhs}, {opts})              *nvim_set_keymap()*
       • {lhs}   Left-hand-side |{lhs}| of the mapping.
       • {rhs}   Right-hand-side |{rhs}| of the mapping.
       • {opts}  Optional parameters map: Accepts all |:map-arguments| as keys
-                except |<buffer>|, values are booleans (default false). Also:
+                except <buffer>, values are booleans (default false). Also:
                 • "noremap" disables |recursive_mapping|, like |:noremap|
                 • "desc" human-readable description.
                 • "callback" Lua function called in place of {rhs}.
@@ -1689,8 +1689,8 @@ nvim_parse_expression({expr}, {flags}, {highlight})
                        operator/space, though also yielding an error).
                      • "l" when needing to start parsing with lvalues for
                        ":let" or ":for". Common flag sets:
-                     • "m" to parse like for ":echo".
-                     • "E" to parse like for "<C-r>=".
+                     • "m" to parse like for `":echo"`.
+                     • "E" to parse like for `"<C-r>="`.
                      • empty string for ":call".
                      • "lm" to parse for ":let".
       • {highlight}  If true, return value will also include "highlight" key
@@ -1714,7 +1714,7 @@ nvim_parse_expression({expr}, {flags}, {highlight})
           • "ast": AST, either nil or a dictionary with these keys:
             • "type": node type, one of the value names from ExprASTNodeType
               stringified without "kExprNode" prefix.
-            • "start": a pair [line, column] describing where node is
+            • "start": a pair `[line, column]` describing where node is
               "started" where "line" is always 0 (will not be 0 if you will be
               using this API on e.g. ":let", but that is not present yet).
               Both elements are Integers.
@@ -1839,22 +1839,21 @@ nvim_create_user_command({name}, {command}, {opts})
                    argument that contains the following keys:
                    • name: (string) Command name
                    • args: (string) The args passed to the command, if any
-                     |<args>|
+                     <args>
                    • fargs: (table) The args split by unescaped whitespace
-                     (when more than one argument is allowed), if any
-                     |<f-args>|
+                     (when more than one argument is allowed), if any <f-args>
                    • nargs: (string) Number of arguments |:command-nargs|
                    • bang: (boolean) "true" if the command was executed with a
-                     ! modifier |<bang>|
+                     ! modifier <bang>
                    • line1: (number) The starting line of the command range
-                     |<line1>|
+                     <line1>
                    • line2: (number) The final line of the command range
-                     |<line2>|
+                     <line2>
                    • range: (number) The number of items in the command range:
-                     0, 1, or 2 |<range>|
-                   • count: (number) Any count supplied |<count>|
-                   • reg: (string) The optional register, if specified |<reg>|
-                   • mods: (string) Command modifiers, if any |<mods>|
+                     0, 1, or 2 <range>
+                   • count: (number) Any count supplied <count>
+                   • reg: (string) The optional register, if specified <reg>
+                   • mods: (string) Command modifiers, if any <mods>
                    • smods: (table) Command modifiers in a structured format.
                      Has the same structure as the "mods" key of
                      |nvim_parse_cmd()|.
@@ -1908,16 +1907,15 @@ nvim_parse_cmd({str}, {opts})                               *nvim_parse_cmd()*
     Return: ~
         Dictionary containing command information, with these keys:
         • cmd: (string) Command name.
-        • range: (array) (optional) Command range (|<line1>| |<line2>|).
-          Omitted if command doesn't accept a range. Otherwise, has no
-          elements if no range was specified, one element if only a single
-          range item was specified, or two elements if both range items were
-          specified.
-        • count: (number) (optional) Command |<count>|. Omitted if command
+        • range: (array) (optional) Command range (<line1> <line2>). Omitted
+          if command doesn't accept a range. Otherwise, has no elements if no
+          range was specified, one element if only a single range item was
+          specified, or two elements if both range items were specified.
+        • count: (number) (optional) Command <count>. Omitted if command
           cannot take a count.
-        • reg: (string) (optional) Command |<register>|. Omitted if command
+        • reg: (string) (optional) Command <register>. Omitted if command
           cannot take a register.
-        • bang: (boolean) Whether command contains a |<bang>| (!) modifier.
+        • bang: (boolean) Whether command contains a <bang> (!) modifier.
         • args: (array) Command arguments.
         • addr: (string) Value of |:command-addr|. Uses short name or "line"
           for -addr=lines.
@@ -2467,9 +2465,9 @@ nvim_buf_set_text({buffer}, {start_row}, {start_col}, {end_row}, {end_col},
     Indexing is zero-based. Row indices are end-inclusive, and column indices
     are end-exclusive.
 
-    To insert text at a given `(row, column)` location, use `start_row =
-    end_row = row` and `start_col = end_col = col`. To delete the text in a
-    range, use `replacement = {}`.
+    To insert text at a given `(row, column)` location, use
+    `start_row = end_row = row` and `start_col = end_col = col`. To delete the
+    text in a range, use `replacement = {}`.
 
     Prefer |nvim_buf_set_lines()| if you are only adding or deleting entire
     lines.
@@ -2639,7 +2637,7 @@ nvim_buf_get_extmarks({buffer}, {ns_id}, {start}, {end}, {opts})
                     "virt_text" and "virt_lines"
 
     Return: ~
-        List of [extmark_id, row, col] tuples in "traversal order".
+        List of `[extmark_id, row, col]` tuples in "traversal order".
 
                                                       *nvim_buf_set_extmark()*
 nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {opts})
@@ -2674,7 +2672,7 @@ nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {opts})
                     EOL of a line, continue the highlight for the rest of the
                     screen line (just like for diff and cursorline highlight).
                   • virt_text : virtual text to link to this mark. A list of
-                    [text, highlight] tuples, each representing a text chunk
+                    `[text, highlight]` tuples, each representing a text chunk
                     with specified highlight. `highlight` element can either
                     be a single highlight group, or an array of multiple
                     highlight groups that will be stacked (highest priority
@@ -2707,13 +2705,14 @@ nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {opts})
                       for "inline" virt_text.
                   • virt_lines : virtual lines to add next to this mark This
                     should be an array over lines, where each line in turn is
-                    an array over [text, highlight] tuples. In general, buffer
-                    and window options do not affect the display of the text.
-                    In particular 'wrap' and 'linebreak' options do not take
-                    effect, so the number of extra screen lines will always
-                    match the size of the array. However the 'tabstop' buffer
-                    option is still used for hard tabs. By default lines are
-                    placed below the buffer line containing the mark.
+                    an array over `[text, highlight]` tuples. In general,
+                    buffer and window options do not affect the display of the
+                    text. In particular 'wrap' and 'linebreak' options do not
+                    take effect, so the number of extra screen lines will
+                    always match the size of the array. However the 'tabstop'
+                    buffer option is still used for hard tabs. By default
+                    lines are placed below the buffer line containing the
+                    mark.
                   • virt_lines_above: place virtual lines above instead.
                   • virt_lines_leftcol: Place extmarks in the leftmost column
                     of the window, bypassing sign and number columns.
@@ -2833,16 +2832,23 @@ nvim_set_decoration_provider({ns_id}, {opts})
     Parameters: ~
       • {ns_id}  Namespace id from |nvim_create_namespace()|
       • {opts}   Table of callbacks:
-                 • on_start: called first on each screen redraw ["start",
-                   tick]
+                 • on_start: called first on each screen redraw >
+                    ["start", tick]
+<
                  • on_buf: called for each buffer being redrawn (before window
-                   callbacks) ["buf", bufnr, tick]
-                 • on_win: called when starting to redraw a specific window.
-                   ["win", winid, bufnr, topline, botline]
+                   callbacks) >
+                    ["buf", bufnr, tick]
+<
+                 • on_win: called when starting to redraw a specific window. >
+                    ["win", winid, bufnr, topline, botline]
+<
                  • on_line: called for each buffer line being redrawn. (The
-                   interaction with fold lines is subject to change) ["line",
-                   winid, bufnr, row]
-                 • on_end: called at the end of a redraw cycle ["end", tick]
+                   interaction with fold lines is subject to change) >
+                    ["line", winid, bufnr, row]
+<
+                 • on_end: called at the end of a redraw cycle >
+                    ["end", tick]
+<
 
 nvim_win_add_ns({window}, {ns_id})                         *nvim_win_add_ns()*
     Adds the namespace scope to the window.
@@ -3181,9 +3187,9 @@ nvim_open_win({buffer}, {enter}, {config})                   *nvim_open_win()*
                   • width: Window width (in character cells). Minimum of 1.
                   • height: Window height (in character cells). Minimum of 1.
                   • bufpos: Places float relative to buffer text (only when
-                    relative="win"). Takes a tuple of zero-indexed [line,
-                    column]. `row` and `col` if given are applied relative to
-                    this position, else they default to:
+                    relative="win"). Takes a tuple of zero-indexed
+                    `[line, column]`. `row` and `col` if given are applied
+                    relative to this position, else they default to:
                     • `row=1` and `col=0` if `anchor` is "NW" or "NE"
                     • `row=0` and `col=0` if `anchor` is "SW" or "SE" (thus
                       like a tooltip near the buffer text).
@@ -3474,9 +3480,9 @@ nvim_create_autocmd({event}, {opts})                   *nvim_create_autocmd()*
                    • event: (string) name of the triggered event
                      |autocmd-events|
                    • group: (number|nil) autocommand group id, if any
-                   • match: (string) expanded value of |<amatch>|
-                   • buf: (number) expanded value of |<abuf>|
-                   • file: (string) expanded value of |<afile>|
+                   • match: (string) expanded value of <amatch>
+                   • buf: (number) expanded value of <abuf>
+                   • file: (string) expanded value of <afile>
                    • data: (any) arbitrary data passed from
                      |nvim_exec_autocmds()|
                  • command (string) optional: Vim command to execute on event.
@@ -3542,7 +3548,7 @@ nvim_exec_autocmds({event}, {opts})                     *nvim_exec_autocmds()*
                  • buffer (integer) optional: buffer number
                    |autocmd-buflocal|. Cannot be used with {pattern}.
                  • modeline (bool) optional: defaults to true. Process the
-                   modeline after the autocommands |<nomodeline>|.
+                   modeline after the autocommands <nomodeline>.
                  • data (any): arbitrary data to send to the autocommand
                    callback. See |nvim_create_autocmd()| for details.
 
diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt
index 1d566efec8..767f46ad1e 100644
--- a/runtime/doc/develop.txt
+++ b/runtime/doc/develop.txt
@@ -184,7 +184,7 @@ Strict "vimdoc" subset:
 
 C docstrings ~
 
-Nvim API documentation lives in the source code, as docstrings (Doxygen
+Nvim API documentation lives in the source code, as docstrings (doc
 comments) on the function definitions.  The |api| :help is generated
 from the docstrings defined in src/nvim/api/*.c.
 
@@ -193,6 +193,8 @@ Docstring format:
 - Special tokens start with `@` followed by the token name:
   `@note`, `@param`, `@return`
 - Markdown is supported.
+- Tags are written as `[tag]()`.
+- References are written as `[tag]`
 - Use ``` for code samples.
   Code samples can be annotated as `vim` or `lua`
 
@@ -235,6 +237,8 @@ definitions.  The |lua-vim| :help is generated from the docstrings.
 Docstring format:
 - Use LuaCATS annotations: https://luals.github.io/wiki/annotations/
 - Markdown is supported.
+- Tags are written as `[tag]()`.
+- References are written as `[tag]`
 - Use ``` for code samples.
   Code samples can be annotated as `vim` or `lua`
 - Use `@nodoc` to prevent documentation generation.
diff --git a/runtime/doc/diagnostic.txt b/runtime/doc/diagnostic.txt
index c61c17c9b0..c9e783ca62 100644
--- a/runtime/doc/diagnostic.txt
+++ b/runtime/doc/diagnostic.txt
@@ -429,7 +429,7 @@ Lua module: vim.diagnostic                                    *diagnostic-api*
       • {float}?             (`boolean|vim.diagnostic.Opts.Float|fun(namespace: integer, bufnr:integer): vim.diagnostic.Opts.Float`)
                              Options for floating windows. See
                              |vim.diagnostic.Opts.Float|.
-      • {update_in_insert}?  (`boolean`, default: `false) Update diagnostics
+      • {update_in_insert}?  (`boolean`, default: `false`) Update diagnostics
                              in Insert mode (if `false`, diagnostics are
                              updated on |InsertLeave|)
       • {severity_sort}?     (`boolean|{reverse?:boolean}`, default: `false)
@@ -486,8 +486,8 @@ Lua module: vim.diagnostic                                    *diagnostic-api*
                             which is prepended to each diagnostic in the
                             window as well as an (optional) highlight group
                             which will be used to highlight the prefix.
-                          • If a `table`, it is interpreted as a `[text,
-                            hl_group]` tuple as in |nvim_echo()|
+                          • If a `table`, it is interpreted as a
+                            `[text, hl_group]` tuple as in |nvim_echo()|
                           • If a `string`, it is prepended to each diagnostic
                             in the window with no highlight. Overrides the
                             setting from |vim.diagnostic.config()|.
@@ -550,10 +550,9 @@ Lua module: vim.diagnostic                                    *diagnostic-api*
                               being evaluated, and {total} is the total number
                               of diagnostics for the line. This can be used to
                               render diagnostic symbols or error codes.
-      • {suffix}?             (`string|(fun(diagnostic:vim.Diagnostic):
-                              string)`) Append diagnostic message with suffix.
-                              This can be used to render an LSP diagnostic
-                              error code.
+      • {suffix}?             (`string|(fun(diagnostic:vim.Diagnostic): string)`)
+                              Append diagnostic message with suffix. This can
+                              be used to render an LSP diagnostic error code.
       • {format}?             (`fun(diagnostic:vim.Diagnostic): string`) The
                               return value is the text used to display the
                               diagnostic. Example: >lua
diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt
index 9b1f2d67cd..eb37cb2a6f 100644
--- a/runtime/doc/lsp.txt
+++ b/runtime/doc/lsp.txt
@@ -719,10 +719,10 @@ formatexpr({opts})                                      *vim.lsp.formatexpr()*
     Provides an interface between the built-in client and a `formatexpr`
     function.
 
-    Currently only supports a single client. This can be set via `setlocal
-    formatexpr=v:lua.vim.lsp.formatexpr()` but will typically or in
-    `on_attach` via `vim.bo[bufnr].formatexpr =
-    'v:lua.vim.lsp.formatexpr(#{timeout_ms:250})'`.
+    Currently only supports a single client. This can be set via
+    `setlocal formatexpr=v:lua.vim.lsp.formatexpr()` but will typically or in
+    `on_attach` via
+    `vim.bo[bufnr].formatexpr = 'v:lua.vim.lsp.formatexpr(#{timeout_ms:250})'`.
 
     Parameters: ~
       • {opts}  (`table?`) A table with the following fields:
@@ -844,11 +844,11 @@ start({config}, {opts})                                      *vim.lsp.start()*
       • {config}  (`vim.lsp.ClientConfig`) Configuration for the server. See
                   |vim.lsp.ClientConfig|.
       • {opts}    (`table?`) Optional keyword arguments
-                  • {reuse_client} (`fun(client: vim.lsp.Client, config:
-                    table): boolean`) Predicate used to decide if a client
-                    should be re-used. Used on all running clients. The
-                    default implementation re-uses a client if name and
-                    root_dir matches.
+                  • {reuse_client}
+                    (`fun(client: vim.lsp.Client, config: table): boolean`)
+                    Predicate used to decide if a client should be re-used.
+                    Used on all running clients. The default implementation
+                    re-uses a client if name and root_dir matches.
                   • {bufnr} (`integer`) Buffer handle to attach to if starting
                     or re-using a client (0 for current).
 
@@ -965,12 +965,12 @@ Lua module: vim.lsp.client                                        *lsp-client*
                                 folders but none are configured.
       • {root_dir}              (`string`)
       • {attached_buffers}      (`table<integer,true>`)
-      • {commands}              (`table<string,fun(command: lsp.Command, ctx:
-                                table)>`) Table of command name to function
-                                which is called if any LSP action (code
-                                action, code lenses, ...) triggers the
-                                command. Client commands take precedence over
-                                the global command registry.
+      • {commands}              (`table<string,fun(command: lsp.Command, ctx: table)>`)
+                                Table of command name to function which is
+                                called if any LSP action (code action, code
+                                lenses, ...) triggers the command. Client
+                                commands take precedence over the global
+                                command registry.
       • {settings}              (`table`) Map with language server specific
                                 settings. These are returned to the language
                                 server if requested via
@@ -991,8 +991,7 @@ Lua module: vim.lsp.client                                        *lsp-client*
                                   request before sending kill -15. If set to
                                   false, nvim exits immediately after sending
                                   the "shutdown" request to the server.
-      • {get_language_id}       (`fun(bufnr: integer, filetype: string):
-                                string`)
+      • {get_language_id}       (`fun(bufnr: integer, filetype: string): string`)
       • {capabilities}          (`lsp.ClientCapabilities`) The capabilities
                                 provided by the client (editor or tool)
       • {dynamic_capabilities}  (`lsp.DynamicCapabilities`)
@@ -1002,7 +1001,7 @@ Lua module: vim.lsp.client                                        *lsp-client*
                                 additional checking. If {handler} is not
                                 specified and if there's no respective global
                                 handler, then an error will occur. Returns:
-                                {status}, {[client_id]}. {status} is a boolean
+                                {status}, {client_id}?. {status} is a boolean
                                 indicating if the notification was successful.
                                 If it is `false`, then it will always be
                                 `false` (the client has shutdown). If {status}
@@ -1012,9 +1011,9 @@ Lua module: vim.lsp.client                                        *lsp-client*
                                 the request.
       • {request_sync}          (`fun(method: string, params: table?, timeout_ms: integer?, bufnr: integer): {err: lsp.ResponseError?, result:any}?, string?`)
                                 err # a dictionary, where
-      • {notify}                (`fun(method: string, params: table?):
-                                boolean`) Sends a notification to an LSP
-                                server. Returns: a boolean to indicate if the
+      • {notify}                (`fun(method: string, params: table?): boolean`)
+                                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).
@@ -1033,9 +1032,9 @@ Lua module: vim.lsp.client                                        *lsp-client*
       • {supports_method}       (`fun(method: string, opts?: {bufnr: integer?}): boolean`)
                                 Checks if a client supports a given method.
                                 Always returns true for unknown off-spec
-                                methods. [opts] is a optional `{bufnr?:
-                                integer}` table. Some language server
-                                capabilities can be file specific.
+                                methods. {opts} is a optional
+                                `{bufnr?: integer}` table. Some language
+                                server capabilities can be file specific.
       • {is_stopped}            (`fun(): boolean`) Checks whether a client is
                                 stopped. Returns: true if the client is fully
                                 stopped.
@@ -1095,22 +1094,21 @@ Lua module: vim.lsp.client                                        *lsp-client*
       • {settings}?           (`table`) Map with language server specific
                               settings. See the {settings} in
                               |vim.lsp.Client|.
-      • {commands}?           (`table<string,fun(command: lsp.Command, ctx:
-                              table)>`) Table that maps string of clientside
-                              commands to user-defined functions. Commands
-                              passed to start_client take precedence over the
-                              global command registry. Each key must be a
-                              unique command name, and the value is a function
-                              which is called if any LSP action (code action,
-                              code lenses, ...) triggers the command.
+      • {commands}?           (`table<string,fun(command: lsp.Command, ctx: table)>`)
+                              Table that maps string of clientside commands to
+                              user-defined functions. Commands passed to
+                              start_client take precedence over the global
+                              command registry. Each key must be a unique
+                              command name, and the value is a function which
+                              is called if any LSP action (code action, code
+                              lenses, ...) triggers the command.
       • {init_options}?       (`table`) Values to pass in the initialization
                               request as `initializationOptions`. See
                               `initialize` in the LSP spec.
       • {name}?               (`string`, default: client-id) Name in log
                               messages.
-      • {get_language_id}?    (`fun(bufnr: integer, filetype: string):
-                              string`) Language ID as string. Defaults to the
-                              filetype.
+      • {get_language_id}?    (`fun(bufnr: integer, filetype: string): string`)
+                              Language ID as string. Defaults to the filetype.
       • {offset_encoding}?    (`'utf-8'|'utf-16'|'utf-32'`) The encoding that
                               the LSP server expects. Client does not verify
                               this is correct.
@@ -2222,8 +2220,7 @@ connect({host}, {port})                                *vim.lsp.rpc.connect()*
       • {port}  (`integer`) port to connect to
 
     Return: ~
-        (`fun(dispatchers: vim.lsp.rpc.Dispatchers):
-        vim.lsp.rpc.PublicClient`)
+        (`fun(dispatchers: vim.lsp.rpc.Dispatchers): vim.lsp.rpc.PublicClient`)
 
                                          *vim.lsp.rpc.domain_socket_connect()*
 domain_socket_connect({pipe_path})
@@ -2239,8 +2236,7 @@ domain_socket_connect({pipe_path})
                      of the named pipe (Windows) to connect to
 
     Return: ~
-        (`fun(dispatchers: vim.lsp.rpc.Dispatchers):
-        vim.lsp.rpc.PublicClient`)
+        (`fun(dispatchers: vim.lsp.rpc.Dispatchers): vim.lsp.rpc.PublicClient`)
 
 format_rpc_error({err})                       *vim.lsp.rpc.format_rpc_error()*
     Constructs an error message from an LSP error object.
@@ -2304,12 +2300,12 @@ start({cmd}, {dispatchers}, {extra_spawn_params})        *vim.lsp.rpc.start()*
     Parameters: ~
       • {cmd}                 (`string[]`) Command to start the LSP server.
       • {dispatchers}         (`table?`) Dispatchers for LSP message types.
-                              • {notification} (`fun(method: string, params:
-                                table)`)
-                              • {server_request} (`fun(method: string, params:
-                                table): any?, lsp.ResponseError?`)
-                              • {on_exit} (`fun(code: integer, signal:
-                                integer)`)
+                              • {notification}
+                                (`fun(method: string, params: table)`)
+                              • {server_request}
+                                (`fun(method: string, params: table): any?, lsp.ResponseError?`)
+                              • {on_exit}
+                                (`fun(code: integer, signal: integer)`)
                               • {on_error} (`fun(code: integer, err: any)`)
       • {extra_spawn_params}  (`table?`) Additional context for the LSP server
                               process.
diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index 03e9ca4dd9..367b5c36d2 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -1408,8 +1408,8 @@ Option:remove({value})                                      *vim.opt:remove()*
 
 vim.bo                                                                *vim.bo*
     Get or set buffer-scoped |options| for the buffer with number {bufnr}. If
-    [{bufnr}] is omitted then the current buffer is used. Invalid {bufnr} or
-    key is an error.
+    {bufnr} is omitted then the current buffer is used. Invalid {bufnr} or key
+    is an error.
 
     Note: this is equivalent to `:setlocal` for |global-local| options and
     `:set` otherwise.
@@ -1459,7 +1459,7 @@ vim.o                                                                  *vim.o*
 vim.wo                                                                *vim.wo*
     Get or set window-scoped |options| for the window with handle {winid} and
     buffer with number {bufnr}. Like `:setlocal` if setting a |global-local|
-    option or if {bufnr} is provided, like `:set` otherwise. If [{winid}] is
+    option or if {bufnr} is provided, like `:set` otherwise. If {winid} is
     omitted then the current window is used. Invalid {winid}, {bufnr} or key
     is an error.
 
@@ -2434,10 +2434,10 @@ vim.loader.find({modname}, {opts})                         *vim.loader.find()*
                      the runtime path.
                    • {paths}? (`string[]`, default: `{}`) Extra paths to
                      search for modname
-                   • {patterns}? (`string[]`, default: `{"/init.lua",
-                     ".lua"}`) List of patterns to use when searching for
-                     modules. A pattern is a string added to the basename of
-                     the Lua module being searched.
+                   • {patterns}? (`string[]`, default:
+                     `{"/init.lua", ".lua"}`) List of patterns to use when
+                     searching for modules. A pattern is a string added to the
+                     basename of the Lua module being searched.
                    • {all}? (`boolean`, default: `false`) Search for all
                      matches.
 
@@ -3139,16 +3139,17 @@ vim.lpeg.Cc({...})                                             *vim.lpeg.Cc()*
 
 vim.lpeg.Cf({patt}, {func})                                    *vim.lpeg.Cf()*
     Creates a fold capture. If `patt` produces a list of captures C1 C2 ...
-    Cn, this capture will produce the value `func(...func(func(C1, C2),
-    C3)...,Cn)`, that is, it will fold (or accumulate, or reduce) the captures
-    from `patt` using function `func`. This capture assumes that `patt` should
-    produce at least one capture with at least one value (of any type), which
-    becomes the initial value of an accumulator. (If you need a specific
-    initial value, you may prefix a constant captureto `patt`.) For each
-    subsequent capture, LPeg calls `func` with this accumulator as the first
-    argument and all values produced by the capture as extra arguments; the
-    first result from this call becomes the new value for the accumulator. The
-    final value of the accumulator becomes the captured value.
+    Cn, this capture will produce the value
+    `func(...func(func(C1, C2), C3)...,Cn)`, that is, it will fold (or
+    accumulate, or reduce) the captures from `patt` using function `func`.
+    This capture assumes that `patt` should produce at least one capture with
+    at least one value (of any type), which becomes the initial value of an
+    accumulator. (If you need a specific initial value, you may prefix a
+    constant captureto `patt`.) For each subsequent capture, LPeg calls `func`
+    with this accumulator as the first argument and all values produced by the
+    capture as extra arguments; the first result from this call becomes the
+    new value for the accumulator. The final value of the accumulator becomes
+    the captured value.
 
     Example: >lua
         local number = lpeg.R('09') ^ 1 / tonumber
diff --git a/runtime/doc/treesitter.txt b/runtime/doc/treesitter.txt
index 7e2559ecd6..5f33802ad5 100644
--- a/runtime/doc/treesitter.txt
+++ b/runtime/doc/treesitter.txt
@@ -719,8 +719,8 @@ get_captures_at_pos({bufnr}, {row}, {col})
       • {col}    (`integer`) Position column
 
     Return: ~
-        (`table[]`) List of captures `{ capture = "name", metadata = { ... }
-        }`
+        (`table[]`) List of captures
+        `{ capture = "name", metadata = { ... } }`
 
 get_node({opts})                                   *vim.treesitter.get_node()*
     Returns the smallest named node at the given position
@@ -1154,8 +1154,8 @@ Query:iter_captures({node}, {source}, {start}, {stop})
                   Defaults to `node:end_()`.
 
     Return: ~
-        (`fun(end_line: integer?): integer, TSNode,
-        vim.treesitter.query.TSMetadata`) capture id, capture node, metadata
+        (`fun(end_line: integer?): integer, TSNode, vim.treesitter.query.TSMetadata`)
+        capture id, capture node, metadata
 
                                                         *Query:iter_matches()*
 Query:iter_matches({node}, {source}, {start}, {stop}, {opts})