Merge pull request #35410 from zeertzjq/vim-308a313

vim-patch: doc updates

runtime/doc/usr_41.txt

@@ -650,6 +650,7 @@ String manipulation:					*string-functions*
 	win_execute()		like execute() but in a specified window
 	trim()			trim characters from a string
 	gettext()		lookup message translation
+	items()			get List of String index-character pairs
 
 List manipulation:					*list-functions*
 	get()			get an item without error for wrong index

runtime/doc/vimfn.txt

@@ -5424,22 +5424,27 @@ isnan({expr})                                                          *isnan()*
                 Return: ~
                   (`0|1`)
 
-items({dict})                                                          *items()*
+items({expr})                                                          *items()*
-		Return a |List| with all the key-value pairs of {dict}.  Each
+		Return a |List| with all key/index and value pairs of {expr}.
-		|List| item is a list with two items: the key of a {dict}
+		Each |List| item is a list with two items:
-		entry and the value of this entry.  The |List| is in arbitrary
+		- for a |Dict|: the key and the value
-		order.  Also see |keys()| and |values()|.
+		- for a |List| or |String|: the index and the value
+		The returned |List| is in arbitrary order for a |Dict|,
+		otherwise it's in ascending order of the index.
+
+		Also see |keys()| and |values()|.
+
 		Example: >vim
+			let mydict = #{a: 'red', b: 'blue'}
 			for [key, value] in items(mydict)
-			   echo key .. ': ' .. value
+			   echo $"{key} = {value}"
 			endfor
+			echo items([1, 2, 3])
+			echo items("foobar")
 <
-		A List or a String argument is also supported.  In these
-		cases, items() returns a List with the index and the value at
-		the index.
 
                 Parameters: ~
-                  • {dict} (`table`)
+                  • {expr} (`table|string`)
 
                 Return: ~
                   (`any`)

runtime/lua/vim/_meta/vimfn.lua

@@ -4908,22 +4908,27 @@ function vim.fn.islocked(expr) end
 --- @return 0|1
 function vim.fn.isnan(expr) end
 
---- Return a |List| with all the key-value pairs of {dict}.  Each
+--- Return a |List| with all key/index and value pairs of {expr}.
---- |List| item is a list with two items: the key of a {dict}
+--- Each |List| item is a list with two items:
---- entry and the value of this entry.  The |List| is in arbitrary
+--- - for a |Dict|: the key and the value
---- order.  Also see |keys()| and |values()|.
+--- - for a |List| or |String|: the index and the value
---- Example: >vim
+--- The returned |List| is in arbitrary order for a |Dict|,
----   for [key, value] in items(mydict)
+--- otherwise it's in ascending order of the index.
----      echo key .. ': ' .. value
----   endfor
---- <
---- A List or a String argument is also supported.  In these
---- cases, items() returns a List with the index and the value at
---- the index.
 ---
---- @param dict table
+--- Also see |keys()| and |values()|.
+---
+--- Example: >vim
+---   let mydict = #{a: 'red', b: 'blue'}
+---   for [key, value] in items(mydict)
+---      echo $"{key} = {value}"
+---   endfor
+---   echo items([1, 2, 3])
+---   echo items("foobar")
+--- <
+---
+--- @param expr table|string
 --- @return any
-function vim.fn.items(dict) end
+function vim.fn.items(expr) end
 
 --- @deprecated
 --- Obsolete name for |chanclose()|

src/nvim/eval.lua

@@ -6057,22 +6057,27 @@ M.funcs = {
     args = 1,
     base = 1,
     desc = [=[
-      Return a |List| with all the key-value pairs of {dict}.  Each
+      Return a |List| with all key/index and value pairs of {expr}.
-      |List| item is a list with two items: the key of a {dict}
+      Each |List| item is a list with two items:
-      entry and the value of this entry.  The |List| is in arbitrary
+      - for a |Dict|: the key and the value
-      order.  Also see |keys()| and |values()|.
+      - for a |List| or |String|: the index and the value
+      The returned |List| is in arbitrary order for a |Dict|,
+      otherwise it's in ascending order of the index.
+
+      Also see |keys()| and |values()|.
+
       Example: >vim
+      	let mydict = #{a: 'red', b: 'blue'}
       	for [key, value] in items(mydict)
-      	   echo key .. ': ' .. value
+      	   echo $"{key} = {value}"
       	endfor
+      	echo items([1, 2, 3])
+      	echo items("foobar")
       <
-      A List or a String argument is also supported.  In these
-      cases, items() returns a List with the index and the value at
-      the index.
     ]=],
     name = 'items',
-    params = { { 'dict', 'table' } },
+    params = { { 'expr', 'table|string' } },
-    signature = 'items({dict})',
+    signature = 'items({expr})',
   },
   jobclose = {
     args = { 1, 2 },