docs: misc

fix https://github.com/neovim/neovim.github.io/issues/419

Co-authored-by: Rob Pilling <robpilling@gmail.com>

5 files changed, 54 insertions, 53 deletions

diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua
index 38bf263aaf..039d5c7372 100644
--- a/runtime/lua/vim/_meta/api.lua
+++ b/runtime/lua/vim/_meta/api.lua
@@ -1721,8 +1721,7 @@ function vim.api.nvim_open_term(buffer, opts) end
 --- If -1 is provided, a top-level split will be created. `vertical` and `split` are
 --- only valid for normal windows, and are used to control split direction. For `vertical`,
 --- the exact direction is determined by 'splitright' and 'splitbelow'.
---- Split windows cannot have `bufpos`/`row`/`col`/`border`/`title`/`footer`
---- properties.
+--- Split windows cannot have `bufpos`, `row`, `col`, `border`, `title`, `footer` properties.
 ---
 --- With relative=editor (row=0,col=0) refers to the top-left corner of the
 --- screen-grid and (row=Lines-1,col=Columns-1) refers to the bottom-right
@@ -1735,23 +1734,19 @@ function vim.api.nvim_open_term(buffer, opts) end
 --- could let floats hover outside of the main window like a tooltip, but
 --- this should not be used to specify arbitrary WM screen positions.
 ---
---- Example: window-relative float
+--- Examples:
 ---
 --- ```lua
---- vim.api.nvim_open_win(0, false,
----   {relative='win', row=3, col=3, width=12, height=3})
---- ```
+--- -- Window-relative float with 'statusline' enabled:
+--- local w1 = vim.api.nvim_open_win(0, false,
+---   {relative='win', row=3, col=3, width=40, height=4})
+--- vim.wo[w1].statusline = vim.o.statusline
 ---
---- Example: buffer-relative float (travels as buffer is scrolled)
----
---- ```lua
+--- -- Buffer-relative float (travels as buffer is scrolled):
 --- vim.api.nvim_open_win(0, false,
----   {relative='win', width=12, height=3, bufpos={100,10}})
---- ```
----
---- Example: vertical split left of the current window
+---   {relative='win', width=40, height=4, bufpos={100,10}})
 ---
---- ```lua
+--- -- Vertical split left of the current window:
 --- vim.api.nvim_open_win(0, false, { split = 'left', win = 0, })
 --- ```
 ---
@@ -1957,7 +1952,7 @@ function vim.api.nvim_parse_cmd(str, opts) end
 ---   - "error": Dict with error, present only if parser saw some
 ---            error. Contains the following keys:
 ---     - "message": String, error message in printf format, translated.
----                  Must contain exactly one "%.*s".
+---                  Must contain exactly one `%.*s`.
 ---     - "arg": String, error message argument.
 ---   - "len": Amount of bytes successfully parsed. With flags equal to ""
 ---            that should be equal to the length of expr string.
diff --git a/runtime/lua/vim/_meta/options.lua b/runtime/lua/vim/_meta/options.lua
index f847ee1520..38f754c273 100644
--- a/runtime/lua/vim/_meta/options.lua
+++ b/runtime/lua/vim/_meta/options.lua
@@ -4398,7 +4398,7 @@ vim.go.mmd = vim.go.maxmapdepth
 --- behaves like CTRL-C was typed.
 --- Running into the limit often means that the pattern is very
 --- inefficient or too complex.  This may already happen with the pattern
---- "\(.\)*" on a very long line.  ".*" works much better.
+--- `\(.\)*` on a very long line.  `.*` works much better.
 --- Might also happen on redraw, when syntax rules try to match a complex
 --- text structure.
 --- Vim may run out of memory before hitting the 'maxmempattern' limit, in
diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua
index f8c0ea337c..7e40b542ef 100644
--- a/runtime/lua/vim/_meta/vimfn.lua
+++ b/runtime/lua/vim/_meta/vimfn.lua
@@ -212,8 +212,9 @@ function vim.fn.assert_beeps(cmd) end
 --- always matters.
 --- Example: >vim
 ---   call assert_equal('foo', 'bar', 'baz')
---- <Will add the following to |v:errors|:
----   test.vim line 12: baz: Expected 'foo' but got 'bar' ~
+--- <Will add the following to |v:errors|: >
+---   test.vim line 12: baz: Expected 'foo' but got 'bar'
+--- <
 ---
 --- @param expected any
 --- @param actual any
@@ -336,8 +337,9 @@ function vim.fn.assert_inrange(lower, upper, actual, msg) end
 ---
 --- Example: >vim
 ---   call assert_match('^f.*o$', 'foobar')
---- <Will result in a string to be added to |v:errors|:
----   test.vim line 12: Pattern '^f.*o$' does not match 'foobar' ~
+--- <Will result in a string to be added to |v:errors|: >
+---   test.vim line 12: Pattern '^f.*o$' does not match 'foobar'
+--- <
 ---
 --- @param pattern string
 --- @param actual string
@@ -6820,54 +6822,54 @@ function vim.fn.prevnonblank(lnum) end
 ---           *E1500*
 --- You cannot mix positional and non-positional arguments: >vim
 ---     echo printf("%s%1$s", "One", "Two")
---- <    E1500: Cannot mix positional and non-positional arguments:
----     %s%1$s
----
+---     " E1500: Cannot mix positional and non-positional arguments:
+---     " %s%1$s
+--- <
 ---           *E1501*
 --- You cannot skip a positional argument in a format string: >vim
 ---     echo printf("%3$s%1$s", "One", "Two", "Three")
---- <    E1501: format argument 2 unused in $-style format:
----     %3$s%1$s
----
+---     " E1501: format argument 2 unused in $-style format:
+---     " %3$s%1$s
+--- <
 ---           *E1502*
 --- You can re-use a [field-width] (or [precision]) argument: >vim
 ---     echo printf("%1$d at width %2$d is: %01$*2$d", 1, 2)
---- <    1 at width 2 is: 01
----
+---     " 1 at width 2 is: 01
+--- <
 --- However, you can't use it as a different type: >vim
 ---     echo printf("%1$d at width %2$ld is: %01$*2$d", 1, 2)
---- <    E1502: Positional argument 2 used as field width reused as
----     different type: long int/int
----
+---     " E1502: Positional argument 2 used as field width reused as
+---     " different type: long int/int
+--- <
 ---           *E1503*
 --- When a positional argument is used, but not the correct number
 --- or arguments is given, an error is raised: >vim
 ---     echo printf("%1$d at width %2$d is: %01$*2$.*3$d", 1, 2)
---- <    E1503: Positional argument 3 out of bounds: %1$d at width
----     %2$d is: %01$*2$.*3$d
----
+---     " E1503: Positional argument 3 out of bounds: %1$d at width
+---     " %2$d is: %01$*2$.*3$d
+--- <
 --- Only the first error is reported: >vim
 ---     echo printf("%01$*2$.*3$d %4$d", 1, 2)
---- <    E1503: Positional argument 3 out of bounds: %01$*2$.*3$d
----     %4$d
----
+---     " E1503: Positional argument 3 out of bounds: %01$*2$.*3$d
+---     " %4$d
+--- <
 ---           *E1504*
 --- A positional argument can be used more than once: >vim
 ---     echo printf("%1$s %2$s %1$s", "One", "Two")
---- <    One Two One
----
+---     " One Two One
+--- <
 --- However, you can't use a different type the second time: >vim
 ---     echo printf("%1$s %2$s %1$d", "One", "Two")
---- <    E1504: Positional argument 1 type used inconsistently:
----     int/string
----
+---     " E1504: Positional argument 1 type used inconsistently:
+---     " int/string
+--- <
 ---           *E1505*
 --- Various other errors that lead to a format string being
 --- wrongly formatted lead to: >vim
 ---     echo printf("%1$d at width %2$d is: %01$*2$.3$d", 1, 2)
---- <    E1505: Invalid format specifier: %1$d at width %2$d is:
----     %01$*2$.3$d
----
+---     " E1505: Invalid format specifier: %1$d at width %2$d is:
+---     " %01$*2$.3$d
+--- <
 ---           *E1507*
 --- This internal error indicates that the logic to parse a
 --- positional format argument ran into a problem that couldn't be
diff --git a/runtime/lua/vim/lsp.lua b/runtime/lua/vim/lsp.lua
index 54b7cd047f..233bbe3f3d 100644
--- a/runtime/lua/vim/lsp.lua
+++ b/runtime/lua/vim/lsp.lua
@@ -515,8 +515,11 @@ local function lsp_enable_callback(bufnr)
   end
 end
 
---- Auto-starts LSP when a buffer is opened, based on the |lsp-config| `filetypes`, `root_markers`,
---- and `root_dir` fields.
+--- Auto-activates LSP in each buffer based on the |lsp-config| `filetypes`, `root_markers`, and
+--- `root_dir`.
+---
+--- To disable, pass `enable=false`: Stops related clients and servers (force-stops servers after
+--- a timeout, unless `exit_timeout=false`).
 ---
 --- Examples:
 ---
@@ -549,8 +552,9 @@ end
 ---@since 13
 ---
 --- @param name string|string[] Name(s) of client(s) to enable.
---- @param enable? boolean `true|nil` to enable, `false` to disable (actively stops and detaches
---- clients as needed, and force stops them if necessary after `client.exit_timeout` milliseconds)
+--- @param enable? boolean If `true|nil`, enables auto-activation of the given LSP config on current
+--- and future buffers. If `false`, disables auto-activation and stops related LSP clients and
+--- servers (force-stops servers after `exit_timeout` milliseconds).
 function lsp.enable(name, enable)
   validate('name', name, { 'string', 'table' })
 
@@ -1055,8 +1059,8 @@ end
 --- vim.lsp.stop_client(vim.lsp.get_clients())
 --- ```
 ---
---- By default asks the server to shutdown, unless stop was requested
---- already for this client, then force-shutdown is attempted.
+--- By default asks the server to shutdown, unless stop was requested already for this client (then
+--- force-shutdown is attempted, unless `exit_timeout=false`).
 ---
 ---@deprecated
 ---@param client_id integer|integer[]|vim.lsp.Client[] id, list of id's, or list of |vim.lsp.Client| objects
diff --git a/runtime/lua/vim/lsp/client.lua b/runtime/lua/vim/lsp/client.lua
index 51749cb2b4..7844eaeb92 100644
--- a/runtime/lua/vim/lsp/client.lua
+++ b/runtime/lua/vim/lsp/client.lua
@@ -75,7 +75,7 @@ local all_clients = {}
 --- (default: `false`)
 --- @field exit_timeout? integer|boolean
 ---
---- A table with flags for the client. The current (experimental) flags are:
+--- Experimental client flags:
 --- @field flags? vim.lsp.Client.Flags
 ---
 --- Language ID as string. Defaults to the buffer filetype.
@@ -163,7 +163,7 @@ local all_clients = {}
 --- (default: `false`)
 --- @field exit_timeout integer|boolean
 ---
---- A table with flags for the client. The current (experimental) flags are:
+--- Experimental client flags:
 --- @field flags vim.lsp.Client.Flags
 ---
 --- See [vim.lsp.ClientConfig].