Merge #38882 docs

4 files changed, 13 insertions, 7 deletions

diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c
index 29021dfe73..87abf479ee 100644
--- a/src/nvim/api/vim.c
+++ b/src/nvim/api/vim.c
@@ -889,6 +889,7 @@ Union(Integer, String) nvim_echo(ArrayOf(Tuple(String, *HLGroupID)) chunks, Bool
   const int save_lines_left = lines_left;
   const bool save_msg_didany = msg_didany;
   // Similar truncation method to showmode().
+  // TODO(justinmk): drop _truncate feature after ui2 graduates?
   if (opts->_truncate) {
     no_wait_return++;
     lines_left = 0;
diff --git a/src/nvim/eval.lua b/src/nvim/eval.lua
index a52b066021..64ff28c61d 100644
--- a/src/nvim/eval.lua
+++ b/src/nvim/eval.lua
@@ -4100,7 +4100,7 @@ M.funcs = {
     args = 1,
     base = 1,
     desc = [=[
-      Returns the last modification time of the given file {fname}.
+      Returns the last modification time ("mtime") of file {fname}.
       The value is measured as seconds since 1st Jan 1970, and may
       be passed to |strftime()|.  See also
       |localtime()| and |strftime()|.
diff --git a/src/nvim/keycodes.c b/src/nvim/keycodes.c
index 9780c3ab07..ef067f68e2 100644
--- a/src/nvim/keycodes.c
+++ b/src/nvim/keycodes.c
@@ -635,11 +635,16 @@ int get_mouse_button(int code, bool *is_click, bool *is_drag)
   return 0;         // Shouldn't get here
 }
 
-/// Replace any terminal code strings with the equivalent internal representation.
+/// Encode `<key>` notation into Nvim's internal key representation. (Does NOT process raw terminal
+/// escape sequences, despite the legacy "termcode" terminology.)
 ///
-/// Used for the "from" and "to" part of a mapping, and the "to" part of a menu command.
-/// Any strings like "<C-UP>" are also replaced, unless `special` is false.
-/// K_SPECIAL by itself is replaced by K_SPECIAL KS_SPECIAL KE_FILLER.
+/// Parses keycode notation like `<C-Up>`, `<CR>`, `<Esc>`, `<F1>`, `<Leader>`, `<SID>`, and emits
+/// the corresponding K_SPECIAL byte sequences. Used for the lhs/rhs of mappings, the rhs of menu
+/// commands, and feedkeys input. K_SPECIAL by itself is replaced by K_SPECIAL KS_SPECIAL KE_FILLER.
+///
+/// Also handles `<C-v>` / backslash literal escapes (per 'cpoptions'), `<Leader>`/`<LocalLeader>`
+/// expansion, `<SID>` script-id substitution, and (unless REPTERM_NO_SIMPLIFY) simplifications like
+/// `<C-H>` => 0x08.
 ///
 /// When "flags" has REPTERM_FROM_PART, trailing <C-v> is included, otherwise it is removed (to make
 /// ":map xx ^V" map xx to nothing). When cpo_val contains CPO_BSLASH, a backslash can be used in
diff --git a/src/nvim/options.lua b/src/nvim/options.lua
index f33a591475..88789825b4 100644
--- a/src/nvim/options.lua
+++ b/src/nvim/options.lua
@@ -8826,8 +8826,8 @@ local options = {
           %-0{minwid}.{maxwid}{item}
         <
         All fields except {item} are optional.  Use "%%" to show a literal "%"
-        char.  Setting this option to empty (`:set statusline=`) sets its
-        value to the default.
+        char.  Setting to empty (`:set statusline=`) sets the global value to
+        the default.
 
         						*stl-%!*
         When the option starts with "%!" then it is used as an expression,