docs: misc

Co-authored-by: Kevin Pham <keevan.pham@gmail.com>

3 files changed, 18 insertions, 24 deletions

diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua
index 3622ba5d19..c0e4e35e7d 100644
--- a/runtime/lua/vim/_meta/api.lua
+++ b/runtime/lua/vim/_meta/api.lua
@@ -691,8 +691,8 @@ function vim.api.nvim_call_function(fn, args) end
 --- @param data string data to write. 8-bit clean: can contain NUL bytes.
 function vim.api.nvim_chan_send(chan, data) end
 
---- Clear all autocommands that match the corresponding {opts}. To delete a
---- particular autocmd, see `nvim_del_autocmd()`.
+--- Clears all autocommands selected by {opts}. To delete autocmds see
+--- `nvim_del_autocmd()`.
 ---
 --- @param opts vim.api.keyset.clear_autocmds Parameters
 ---             • event: (string|table) Examples:
@@ -919,10 +919,9 @@ function vim.api.nvim_del_augroup_by_id(id) end
 --- @param name string String The name of the group.
 function vim.api.nvim_del_augroup_by_name(name) end
 
---- Delete an autocommand by id.
---- NOTE: Only autocommands created via the API have an id.
+--- Deletes an autocommand by id.
 ---
---- @param id integer Integer The id returned by nvim_create_autocmd
+--- @param id integer Integer Autocommand id returned by `nvim_create_autocmd()`
 function vim.api.nvim_del_autocmd(id) end
 
 --- Deletes the current line.
diff --git a/runtime/lua/vim/iter.lua b/runtime/lua/vim/iter.lua
index 7bffcc9c20..a278e96a5f 100644
--- a/runtime/lua/vim/iter.lua
+++ b/runtime/lua/vim/iter.lua
@@ -1,22 +1,15 @@
 ---@defgroup vim.iter
 ---
---- This module provides a generic interface for working with
---- iterables: tables, lists, iterator functions, pair()/ipair()-like iterators,
---- and \`vim.iter()\` objects.
----
---- \*vim.iter()\* wraps its table or function argument into an \*Iter\* object
---- with methods (such as |Iter:filter()| and |Iter:map()|) that transform the
---- underlying source data. These methods can be chained together to create
---- iterator "pipelines". Each pipeline stage receives as input the output
---- values from the prior stage. The values used in the first stage of the
---- pipeline depend on the type passed to this function:
+--- \*vim.iter()\* is an interface for |iterable|s: it wraps a table or function argument into an
+--- \*Iter\* object with methods (such as |Iter:filter()| and |Iter:map()|) that transform the
+--- underlying source data. These methods can be chained together to create iterator "pipelines".
+--- Each pipeline stage receives as input the output values from the prior stage. The values used in
+--- the first stage of the pipeline depend on the type passed to this function:
 ---
 --- - List tables pass only the value of each element
---- - Non-list tables pass both the key and value of each element
---- - Function iterators pass all of the values returned by their respective
----   function
---- - Tables with a metatable implementing __call are treated as function
----   iterators
+--- - Non-list (dict) tables pass both the key and value of each element
+--- - Function |iterator|s pass all of the values returned by their respective function
+--- - Tables with a metatable implementing |__call()| are treated as function iterators
 ---
 --- Examples:
 --- <pre>lua
diff --git a/runtime/lua/vim/shared.lua b/runtime/lua/vim/shared.lua
index 291b003d87..5ce5b200d3 100644
--- a/runtime/lua/vim/shared.lua
+++ b/runtime/lua/vim/shared.lua
@@ -60,7 +60,8 @@ function vim.deepcopy(orig)
   return deepcopy(orig)
 end
 
---- Splits a string at each instance of a separator.
+--- Gets an |iterator| that splits a string at each instance of a separator, in "lazy" fashion
+--- (as opposed to |vim.split()| which is "eager").
 ---
 --- Example:
 ---   <pre>lua
@@ -159,7 +160,8 @@ function vim.gsplit(s, sep, opts)
   end
 end
 
---- Splits a string at each instance of a separator.
+--- Splits a string at each instance of a separator and returns the result as a table (unlike
+--- |vim.gsplit()|).
 ---
 --- Examples:
 --- <pre>lua
@@ -530,8 +532,8 @@ end
 ---
 ---@see Based on https://github.com/premake/premake-core/blob/master/src/base/table.lua
 ---
----@param t table List-like table
----@return iterator over sorted keys and their values
+---@param t table Dict-like table
+---@return # iterator over sorted keys and their values
 function vim.spairs(t)
   assert(type(t) == 'table', string.format('Expected table, got %s', type(t)))