docs: various fixes (#28208)

Co-authored-by: Evgeni Chasnovski <evgeni.chasnovski@gmail.com>
Co-authored-by: Famiu Haque <famiuhaque@proton.me>
Co-authored-by: Gregory Anders <greg@gpanders.com>
Co-authored-by: Guilherme Soares <guilhermesoares1970@gmail.com>
Co-authored-by: Jannik Buhr <jannik.m.buhr@gmail.com>
Co-authored-by: thomaswuhoileong <72001875+thomaswuhoileong@users.noreply.github.com>
Co-authored-by: tom-anders <13141438+tom-anders@users.noreply.github.com>
Co-authored-by: zeertzjq <zeertzjq@outlook.com>

14 files changed, 32 insertions, 22 deletions

diff --git a/.mailmap b/.mailmap
index ffef9f280b..a0af0033a1 100644
--- a/.mailmap
+++ b/.mailmap
@@ -8,15 +8,12 @@ Anmol Sethi <hi@nhooyr.io> <nhooyr@users.noreply.github.com>
 BK1603 <chouhan.shreyansh2702@gmail.com> Shreyansh Chouhan
 Billy Su <g4691821@gmail.com> Billy SU
 Billy Vong <billyvg@gmail.com> <billyvg@users.noreply.github.com>
-bfredl <bjorn.linse@gmail.com>
 Carlos Hernandez <carlos@techbyte.ca> <hurricanehrndz@users.noreply.github.com>
 Chris Kipp <ckipp@pm.me> ckipp01
 Christian Clason <c.clason@uni-graz.at> <christian.clason@uni-due.de>
 Cédric Barreteau <> <cbarrete@users.noreply.github.com>
 Dan Aloni <alonid@gmail.com> <dan@kernelim.com>
 Daniel Hahler <git@thequod.de> <github@thequod.de>
-dundargoc <gocdundar@gmail.com> <33953936+dundargoc@users.noreply.github.com>
-dundargoc <gocdundar@gmail.com> Dundar Goc
 Eisuke Kawashima <e-kwsm@users.noreply.github.com> E Kawashima
 ElPiloto <luis.r.piloto@gmail.com> Luis Piloto
 Eliseo Martínez <eliseomarmol@gmail.com> Eliseo Martínez
@@ -38,6 +35,7 @@ J Phani Mahesh <phanimahesh@gmail.com> <github@phanimahesh.me>
 Jack Bracewell <FriedSock@users.noreply.github.com> <jack.bracewell@unboxedconsulting.com>
 Jack Bracewell <FriedSock@users.noreply.github.com> <jbtwentythree@gmail.com>
 Jacques Germishuys <jacquesg@striata.com> <jacquesg@users.noreply.github.com>
+Jaehwang Jung <tomtomjhj@gmail.com> Jaehwang Jerry Jung
 Jakub Łuczyński <doubleloop@o2.pl> <doubleloop@users.noreply.github.com>
 James McCoy <jamessan@jamessan.com> <vega.james@gmail.com>
 Jan Edmund Lazo <jan.lazo@mail.utoronto.ca> <janedmundlazo@hotmail.com>
@@ -57,6 +55,8 @@ Kwon-Young Choi <kwon-young.choi@hotmail.fr> Kwon-Young
 Lewis Russell <lewis6991@gmail.com> <me@lewisr.dev>
 Lucas Hoffmann <l-m-h@web.de> <lucc@posteo.de>
 Lucas Hoffmann <l-m-h@web.de> <lucc@users.noreply.github.com>
+Luuk van Baal <luukvbaal@gmail.com> <31730729+luukvbaal@users.noreply.github.com>
+Luuk van Baal <luukvbaal@gmail.com> luukvbaal
 Marco Hinz <mh.codebro@gmail.com> <mh.codebro+github@gmail.com>
 Marvim the Paranoid Android <marvim@users.noreply.github.com> marvim
 Mateusz Czapliński <czapkofan@gmail.com> Mateusz Czaplinski
@@ -111,14 +111,20 @@ Yorick Peterse <git@yorickpeterse.com> <yorick@yorickpeterse.com>
 ZyX <kp-pav@yandex.ru> <kp-pav@ya.ru>
 ZyX <kp-pav@yandex.ru> Nikolai Aleksandrovich Pavlov
 aph <a.hewson@gmail.com> Ashley Hewson
+bfredl <bjorn.linse@gmail.com>
 butwerenotthereyet <58348703+butwerenotthereyet@users.noreply.github.com> We're Yet
 chemzqm <chemzqm@gmail.com> Qiming zhao
 chentau <tchen1998@gmail.com> Tony Chen
 dedmass <carlo.abelli@gmail.com> Carlo Abelli
+dundargoc <gocdundar@gmail.com> <33953936+dundargoc@users.noreply.github.com>
+dundargoc <gocdundar@gmail.com> Dundar Goc
 equal-l2 <eng.equall2@gmail.com> <equal-l2@users.noreply.github.com>
 francisco souza <fsouza@users.noreply.github.com> <108725+fsouza@users.noreply.github.com>
 glacambre <code@lacamb.re> <me@r4>
 glacambre <code@lacamb.re> Ghjuvan Lacambre
+glepnir <glephunter@gmail.com> Raphael
+glepnir <glepnir@gopherhub.org> Raphael
+glepnir <glepnir@neovim.pro> Raphael
 ii14 <ii14@users.noreply.github.com> <59243201+ii14@users.noreply.github.com>
 jdrouhard <john@jmdtech.org> <github@jmdtech.org>
 kuuote <znmxodq1@gmail.com> <36663503+kuuote@users.noreply.github.com>
diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt
index 9e9c48e099..c44db11acd 100644
--- a/runtime/doc/options.txt
+++ b/runtime/doc/options.txt
@@ -1442,7 +1442,7 @@ A jump table for the options with a short description can be found at |Q_op|.
 'commentstring' 'cms'	string	(default "")
 			local to buffer
 	A template for a comment.  The "%s" in the value is replaced with the
-	comment text.  For example, C uses "/*%s*/". Currently only used to
+	comment text. For example, C uses "/*%s*/". Used for |commenting| and to
 	add markers for folding, see |fold-marker|.
 
 						*'complete'* *'cpt'* *E535*
diff --git a/runtime/doc/vvars.txt b/runtime/doc/vvars.txt
index e71e31abf8..de7f23a34d 100644
--- a/runtime/doc/vvars.txt
+++ b/runtime/doc/vvars.txt
@@ -60,9 +60,10 @@ v:collate
 
 			*v:completed_item* *completed_item-variable*
 v:completed_item
-		Dictionary containing the most recent |complete-items| after
-		|CompleteDone|.  Empty if the completion failed, or after
-		leaving and re-entering insert mode.
+		Dictionary containing the |complete-items| for the most
+		recently completed word after |CompleteDone|.  Empty if the
+		completion failed, or after leaving and re-entering insert
+		mode.
 		Note: Plugins can modify the value to emulate the builtin
 		|CompleteDone| event behavior.
 
diff --git a/runtime/ftplugin/tutor.vim b/runtime/ftplugin/tutor.vim
index 30783d9799..45ee582cba 100644
--- a/runtime/ftplugin/tutor.vim
+++ b/runtime/ftplugin/tutor.vim
@@ -19,7 +19,7 @@ setlocal noundofile
 setlocal keywordprg=:help
 setlocal iskeyword=@,-,_
 
-" The user will have to enable the folds himself, but we provide the foldexpr
+" The user will have to enable the folds themself, but we provide the foldexpr
 " function.
 setlocal foldmethod=manual
 setlocal foldexpr=tutor#TutorFolds()
diff --git a/runtime/lua/vim/_comment.lua b/runtime/lua/vim/_comment.lua
index e9cd662c9d..b6cb6c9884 100644
--- a/runtime/lua/vim/_comment.lua
+++ b/runtime/lua/vim/_comment.lua
@@ -80,7 +80,7 @@ local function make_comment_check(parts)
   -- <possible whitespace> <left> <anything> <right> <possible whitespace>
   local nonblank_regex = '^%s-' .. l_esc .. '.*' .. r_esc .. '%s-$'
 
-  -- Commented blank line can have any amoung of whitespace around parts
+  -- Commented blank line can have any amount of whitespace around parts
   local blank_regex = '^%s-' .. vim.trim(l_esc) .. '%s*' .. vim.trim(r_esc) .. '%s-$'
 
   return function(line)
diff --git a/runtime/lua/vim/_meta/options.lua b/runtime/lua/vim/_meta/options.lua
index 9aa20f59bc..b51f82401b 100644
--- a/runtime/lua/vim/_meta/options.lua
+++ b/runtime/lua/vim/_meta/options.lua
@@ -974,7 +974,7 @@ vim.bo.comments = vim.o.comments
 vim.bo.com = vim.bo.comments
 
 --- A template for a comment.  The "%s" in the value is replaced with the
---- comment text.  For example, C uses "/*%s*/". Currently only used to
+--- comment text. For example, C uses "/*%s*/". Used for `commenting` and to
 --- add markers for folding, see `fold-marker`.
 ---
 --- @type string
diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua
index 02d5eaf575..74b8590924 100644
--- a/runtime/lua/vim/_meta/vimfn.lua
+++ b/runtime/lua/vim/_meta/vimfn.lua
@@ -6583,7 +6583,7 @@ function vim.fn.prevnonblank(lnum) end
 ---
 --- @param fmt any
 --- @param expr1? any
---- @return any
+--- @return string
 function vim.fn.printf(fmt, expr1) end
 
 --- Returns the effective prompt text for buffer {buf}.  {buf} can
diff --git a/runtime/lua/vim/_meta/vvars.lua b/runtime/lua/vim/_meta/vvars.lua
index ee6d8ddf35..1660d1dd6c 100644
--- a/runtime/lua/vim/_meta/vvars.lua
+++ b/runtime/lua/vim/_meta/vvars.lua
@@ -54,9 +54,10 @@ vim.v.cmdbang = ...
 --- @type string
 vim.v.collate = ...
 
---- Dictionary containing the most recent `complete-items` after
---- `CompleteDone`.  Empty if the completion failed, or after
---- leaving and re-entering insert mode.
+--- Dictionary containing the `complete-items` for the most
+--- recently completed word after `CompleteDone`.  Empty if the
+--- completion failed, or after leaving and re-entering insert
+--- mode.
 --- Note: Plugins can modify the value to emulate the builtin
 --- `CompleteDone` event behavior.
 --- @type any
diff --git a/runtime/lua/vim/termcap.lua b/runtime/lua/vim/termcap.lua
index 6152f50730..1da2e71839 100644
--- a/runtime/lua/vim/termcap.lua
+++ b/runtime/lua/vim/termcap.lua
@@ -12,7 +12,7 @@ local M = {}
 --- emulator supports the XTGETTCAP sequence.
 ---
 --- @param caps string|table A terminal capability or list of capabilities to query
---- @param cb fun(cap:string, found:bool, seq:string?) Callback function which is called for
+--- @param cb fun(cap:string, found:boolean, seq:string?) Callback function which is called for
 ---           each capability in {caps}. {found} is set to true if the capability was found or false
 ---           otherwise. {seq} is the control sequence for the capability if found, or nil for
 ---           boolean capabilities.
diff --git a/src/nvim/eval.lua b/src/nvim/eval.lua
index 65389ede99..4101ba50fb 100644
--- a/src/nvim/eval.lua
+++ b/src/nvim/eval.lua
@@ -7902,6 +7902,7 @@ M.funcs = {
     name = 'printf',
     params = { { 'fmt', 'any' }, { 'expr1', 'any' } },
     signature = 'printf({fmt}, {expr1} ...)',
+    returns = 'string',
   },
   prompt_getprompt = {
     args = 1,
diff --git a/src/nvim/eval/userfunc.c b/src/nvim/eval/userfunc.c
index 2a3aec1bc7..39bd63462c 100644
--- a/src/nvim/eval/userfunc.c
+++ b/src/nvim/eval/userfunc.c
@@ -2365,7 +2365,7 @@ void ex_function(exarg_T *eap)
   // Read the body of the function, until ":endfunction" is found.
   if (KeyTyped) {
     // Check if the function already exists, don't let the user type the
-    // whole function before telling him it doesn't work!  For a script we
+    // whole function before telling them it doesn't work!  For a script we
     // need to skip the body to be able to find what follows.
     if (!eap->skip && !eap->forceit) {
       if (fudi.fd_dict != NULL && fudi.fd_newkey == NULL) {
diff --git a/src/nvim/options.lua b/src/nvim/options.lua
index d4aceed013..40a5e3ba78 100644
--- a/src/nvim/options.lua
+++ b/src/nvim/options.lua
@@ -1324,7 +1324,7 @@ return {
       defaults = { if_true = '' },
       desc = [=[
         A template for a comment.  The "%s" in the value is replaced with the
-        comment text.  For example, C uses "/*%s*/". Currently only used to
+        comment text. For example, C uses "/*%s*/". Used for |commenting| and to
         add markers for folding, see |fold-marker|.
       ]=],
       full_name = 'commentstring',
diff --git a/src/nvim/vvars.lua b/src/nvim/vvars.lua
index 37cb70c725..224edfaf6e 100644
--- a/src/nvim/vvars.lua
+++ b/src/nvim/vvars.lua
@@ -64,9 +64,10 @@ M.vars = {
   },
   completed_item = {
     desc = [=[
-      Dictionary containing the most recent |complete-items| after
-      |CompleteDone|.  Empty if the completion failed, or after
-      leaving and re-entering insert mode.
+      Dictionary containing the |complete-items| for the most
+      recently completed word after |CompleteDone|.  Empty if the
+      completion failed, or after leaving and re-entering insert
+      mode.
       Note: Plugins can modify the value to emulate the builtin
       |CompleteDone| event behavior.
     ]=],
diff --git a/test/old/testdir/test_filetype.vim b/test/old/testdir/test_filetype.vim
index 9fc2f590a1..564be4ebe2 100644
--- a/test/old/testdir/test_filetype.vim
+++ b/test/old/testdir/test_filetype.vim
@@ -1682,14 +1682,14 @@ func Test_mod_file()
   call assert_equal('pim', b:modula2.dialect)
   bwipe!
 
-  " Modula-2 program MODULE with priorty (and uppercase extension)
+  " Modula-2 program MODULE with priority (and uppercase extension)
   call writefile(['MODULE Module2Mod [42];'], 'Xfile.MOD')
   split Xfile.MOD
   call assert_equal('modula2', &filetype)
   call assert_equal('pim', b:modula2.dialect)
   bwipe!
 
-  " Modula-2 implementation MODULE with priorty (and uppercase extension)
+  " Modula-2 implementation MODULE with priority (and uppercase extension)
   call writefile(['IMPLEMENTATION MODULE Module2Mod [42];'], 'Xfile.MOD')
   split Xfile.MOD
   call assert_equal('modula2', &filetype)