From 6752f1005d26c93a033d856a60b7b296f3e51634 Mon Sep 17 00:00:00 2001
From: "Justin M. Keyes" <justinkz@gmail.com>
Date: Wed, 14 Dec 2022 19:58:18 +0100
Subject: docs: naming conventions, guidelines

close #21063
---
 runtime/lua/vim/keymap.lua | 50 ++++++++++++++++------------------------------
 runtime/lua/vim/ui.lua     |  7 ++++---
 2 files changed, 21 insertions(+), 36 deletions(-)

(limited to 'runtime/lua/vim')

diff --git a/runtime/lua/vim/keymap.lua b/runtime/lua/vim/keymap.lua
index ef1c66ea20..911b584c14 100644
--- a/runtime/lua/vim/keymap.lua
+++ b/runtime/lua/vim/keymap.lua
@@ -1,51 +1,35 @@
 local keymap = {}
 
---- Add a new |mapping|.
+--- Adds a new |mapping|.
 --- Examples:
 --- <pre>lua
----   -- Can add mapping to Lua functions
+---   -- Map to a Lua function:
 ---   vim.keymap.set('n', 'lhs', function() print("real lua function") end)
----
----   -- Can use it to map multiple modes
+---   -- Map to multiple modes:
 ---   vim.keymap.set({'n', 'v'}, '<leader>lr', vim.lsp.buf.references, { buffer=true })
----
----   -- Can add mapping for specific buffer
+---   -- Buffer-local mapping:
 ---   vim.keymap.set('n', '<leader>w', "<cmd>w<cr>", { silent = true, buffer = 5 })
----
----   -- Expr mappings
+---   -- Expr mapping:
 ---   vim.keymap.set('i', '<Tab>', function()
 ---     return vim.fn.pumvisible() == 1 and "<C-n>" or "<Tab>"
 ---   end, { expr = true })
----   -- <Plug> mappings
+---   -- <Plug> mapping:
 ---   vim.keymap.set('n', '[%%', '<Plug>(MatchitNormalMultiBackward)')
 --- </pre>
 ---
---- Note that in a mapping like:
---- <pre>lua
----    vim.keymap.set('n', 'asdf', require('jkl').my_fun)
---- </pre>
----
---- 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:
---- <pre>lua
----    vim.keymap.set('n', 'asdf', function() return require('jkl').my_fun() end)
---- </pre>
----
----@param mode string|table    Same mode short names as |nvim_set_keymap()|.
+---@param mode string|table    Mode short-name, see |nvim_set_keymap()|.
 ---                            Can also be list of modes to create mapping on multiple modes.
 ---@param lhs string           Left-hand side |{lhs}| of the mapping.
----@param rhs string|function  Right-hand side |{rhs}| of the mapping. Can also be a Lua function.
---
----@param opts table|nil A table of |:map-arguments|.
----                      + Accepts options accepted by the {opts} parameter in |nvim_set_keymap()|,
----                        with the following notable differences:
----                        - replace_keycodes: Defaults to `true` if "expr" is `true`.
----                        - noremap: Always overridden with the inverse of "remap" (see below).
----                      + In addition to those options, the table accepts the following keys:
----                        - buffer: (number or boolean) Add a mapping to the given buffer.
----                        When `0` or `true`, use the current buffer.
----                        - remap: (boolean) Make the mapping recursive.
----                        This is the inverse of the "noremap" option from |nvim_set_keymap()|.
+---@param rhs string|function  Right-hand side |{rhs}| of the mapping, can be a Lua function.
+---
+---@param opts table|nil Table of |:map-arguments|.
+---                      - Same as |nvim_set_keymap()| {opts}, except:
+---                        - "replace_keycodes" defaults to `true` if "expr" is `true`.
+---                        - "noremap": inverse of "remap" (see below).
+---                      - Also accepts:
+---                        - "buffer" number|boolean Creates buffer-local mapping, `0` or `true`
+---                        for current buffer.
+---                        - remap: (boolean) Make the mapping recursive. Inverses "noremap".
 ---                        Defaults to `false`.
 ---@see |nvim_set_keymap()|
 function keymap.set(mode, lhs, rhs, opts)
diff --git a/runtime/lua/vim/ui.lua b/runtime/lua/vim/ui.lua
index 8f5be15221..aaee175f3a 100644
--- a/runtime/lua/vim/ui.lua
+++ b/runtime/lua/vim/ui.lua
@@ -1,6 +1,7 @@
 local M = {}
 
---- Prompts the user to pick a single item from a collection of entries
+--- Prompts the user to pick from a list of items, allowing arbitrary (potentially asynchronous)
+--- work until `on_choice`.
 ---
 ---@param items table Arbitrary items
 ---@param opts table Additional options
@@ -35,7 +36,6 @@ local M = {}
 ---     end
 --- end)
 --- </pre>
-
 function M.select(items, opts, on_choice)
   vim.validate({
     items = { items, 'table', false },
@@ -55,7 +55,8 @@ function M.select(items, opts, on_choice)
   end
 end
 
---- Prompts the user for input
+--- Prompts the user for input, allowing arbitrary (potentially asynchronous) work until
+--- `on_confirm`.
 ---
 ---@param opts table Additional options. See |input()|
 ---     - prompt (string|nil)
-- 
cgit