vim-patch:9cd9e759ab1e (#28224)

runtime(doc): Normalise builtin-function optional parameter formatting

These should generally be formatted as func([{arg}]) and referenced as
{arg} in the description.

closes: vim/vim#14438

9cd9e759ab

Co-authored-by: Doug Kearns <dougkearns@gmail.com>

runtime/doc/builtin.txt

@@ -2196,16 +2196,16 @@ getchangelist([{buf}])                                         *getchangelist()*
 		position refers to the position in the list. For other
 		buffers, it is set to the length of the list.
 
-getchar([expr])                                                      *getchar()*
+getchar([{expr}])                                                    *getchar()*
 		Get a single character from the user or input stream.
-		If [expr] is omitted, wait until a character is available.
-		If [expr] is 0, only get a character when one is available.
+		If {expr} is omitted, wait until a character is available.
+		If {expr} is 0, only get a character when one is available.
 			Return zero otherwise.
-		If [expr] is 1, only check if a character is available, it is
+		If {expr} is 1, only check if a character is available, it is
 			not consumed.  Return zero if no character available.
 		If you prefer always getting a string use |getcharstr()|.
 
-		Without [expr] and when [expr] is 0 a whole character or
+		Without {expr} and when {expr} is 0 a whole character or
 		special key is returned.  If it is a single character, the
 		result is a Number.  Use |nr2char()| to convert it to a String.
 		Otherwise a String is returned with the encoded character.
@@ -2215,11 +2215,11 @@ getchar([expr])                                                      *getchar()*
 		also a String when a modifier (shift, control, alt) was used
 		that is not included in the character.
 
-		When [expr] is 0 and Esc is typed, there will be a short delay
+		When {expr} is 0 and Esc is typed, there will be a short delay
 		while Vim waits to see if this is the start of an escape
 		sequence.
 
-		When [expr] is 1 only the first byte is returned.  For a
+		When {expr} is 1 only the first byte is returned.  For a
 		one-byte character it is the character itself as a number.
 		Use nr2char() to convert it to a String.
 
@@ -2311,13 +2311,13 @@ getcharsearch()                                                *getcharsearch()*
 			nnoremap <expr> , getcharsearch().forward ? ',' : ';'
 <		Also see |setcharsearch()|.
 
-getcharstr([expr])                                                *getcharstr()*
+getcharstr([{expr}])                                              *getcharstr()*
 		Get a single character from the user or input stream as a
 		string.
-		If [expr] is omitted, wait until a character is available.
-		If [expr] is 0 or false, only get a character when one is
+		If {expr} is omitted, wait until a character is available.
+		If {expr} is 0 or false, only get a character when one is
 			available.  Return an empty string otherwise.
-		If [expr] is 1 or true, only check if a character is
+		If {expr} is 1 or true, only check if a character is
 			available, it is not consumed.  Return an empty string
 			if no character is available.
 		Otherwise this works like |getchar()|, except that a number
@@ -4981,9 +4981,9 @@ mkdir({name} [, {flags} [, {prot}]])                              *mkdir()* *E73
 		successful or FALSE if the directory creation failed or partly
 		failed.
 
-mode([expr])                                                            *mode()*
+mode([{expr}])                                                          *mode()*
 		Return a string that indicates the current mode.
-		If [expr] is supplied and it evaluates to a non-zero Number or
+		If {expr} is supplied and it evaluates to a non-zero Number or
 		a non-empty String (|non-zero-arg|), then the full mode is
 		returned, otherwise only the first letter is returned.
 		Also see |state()|.

runtime/lua/vim/_meta/vimfn.lua

@@ -2703,14 +2703,14 @@ function vim.fn.getcellwidths() end
 function vim.fn.getchangelist(buf) end
 
 --- Get a single character from the user or input stream.
---- If [expr] is omitted, wait until a character is available.
---- If [expr] is 0, only get a character when one is available.
+--- If {expr} is omitted, wait until a character is available.
+--- If {expr} is 0, only get a character when one is available.
 ---   Return zero otherwise.
---- If [expr] is 1, only check if a character is available, it is
+--- If {expr} is 1, only check if a character is available, it is
 ---   not consumed.  Return zero if no character available.
 --- If you prefer always getting a string use |getcharstr()|.
 ---
---- Without [expr] and when [expr] is 0 a whole character or
+--- Without {expr} and when {expr} is 0 a whole character or
 --- special key is returned.  If it is a single character, the
 --- result is a Number.  Use |nr2char()| to convert it to a String.
 --- Otherwise a String is returned with the encoded character.
@@ -2720,11 +2720,11 @@ function vim.fn.getchangelist(buf) end
 --- also a String when a modifier (shift, control, alt) was used
 --- that is not included in the character.
 ---
---- When [expr] is 0 and Esc is typed, there will be a short delay
+--- When {expr} is 0 and Esc is typed, there will be a short delay
 --- while Vim waits to see if this is the start of an escape
 --- sequence.
 ---
---- When [expr] is 1 only the first byte is returned.  For a
+--- When {expr} is 1 only the first byte is returned.  For a
 --- one-byte character it is the character itself as a number.
 --- Use nr2char() to convert it to a String.
 ---
@@ -2828,10 +2828,10 @@ function vim.fn.getcharsearch() end
 
 --- Get a single character from the user or input stream as a
 --- string.
---- If [expr] is omitted, wait until a character is available.
---- If [expr] is 0 or false, only get a character when one is
+--- If {expr} is omitted, wait until a character is available.
+--- If {expr} is 0 or false, only get a character when one is
 ---   available.  Return an empty string otherwise.
---- If [expr] is 1 or true, only check if a character is
+--- If {expr} is 1 or true, only check if a character is
 ---   available, it is not consumed.  Return an empty string
 ---   if no character is available.
 --- Otherwise this works like |getchar()|, except that a number
@@ -5993,7 +5993,7 @@ function vim.fn.min(expr) end
 function vim.fn.mkdir(name, flags, prot) end
 
 --- Return a string that indicates the current mode.
---- If [expr] is supplied and it evaluates to a non-zero Number or
+--- If {expr} is supplied and it evaluates to a non-zero Number or
 --- a non-empty String (|non-zero-arg|), then the full mode is
 --- returned, otherwise only the first letter is returned.
 --- Also see |state()|.

src/nvim/eval.lua

@@ -3383,14 +3383,14 @@ M.funcs = {
     args = { 0, 1 },
     desc = [=[
       Get a single character from the user or input stream.
-      If [expr] is omitted, wait until a character is available.
-      If [expr] is 0, only get a character when one is available.
+      If {expr} is omitted, wait until a character is available.
+      If {expr} is 0, only get a character when one is available.
       	Return zero otherwise.
-      If [expr] is 1, only check if a character is available, it is
+      If {expr} is 1, only check if a character is available, it is
       	not consumed.  Return zero if no character available.
       If you prefer always getting a string use |getcharstr()|.
 
-      Without [expr] and when [expr] is 0 a whole character or
+      Without {expr} and when {expr} is 0 a whole character or
       special key is returned.  If it is a single character, the
       result is a Number.  Use |nr2char()| to convert it to a String.
       Otherwise a String is returned with the encoded character.
@@ -3400,11 +3400,11 @@ M.funcs = {
       also a String when a modifier (shift, control, alt) was used
       that is not included in the character.
 
-      When [expr] is 0 and Esc is typed, there will be a short delay
+      When {expr} is 0 and Esc is typed, there will be a short delay
       while Vim waits to see if this is the start of an escape
       sequence.
 
-      When [expr] is 1 only the first byte is returned.  For a
+      When {expr} is 1 only the first byte is returned.  For a
       one-byte character it is the character itself as a number.
       Use nr2char() to convert it to a String.
 
@@ -3449,7 +3449,7 @@ M.funcs = {
     name = 'getchar',
     params = {},
     returns = 'integer',
-    signature = 'getchar([expr])',
+    signature = 'getchar([{expr}])',
   },
   getcharmod = {
     desc = [=[
@@ -3526,10 +3526,10 @@ M.funcs = {
     desc = [=[
       Get a single character from the user or input stream as a
       string.
-      If [expr] is omitted, wait until a character is available.
-      If [expr] is 0 or false, only get a character when one is
+      If {expr} is omitted, wait until a character is available.
+      If {expr} is 0 or false, only get a character when one is
       	available.  Return an empty string otherwise.
-      If [expr] is 1 or true, only check if a character is
+      If {expr} is 1 or true, only check if a character is
       	available, it is not consumed.  Return an empty string
       	if no character is available.
       Otherwise this works like |getchar()|, except that a number
@@ -3538,7 +3538,7 @@ M.funcs = {
     name = 'getcharstr',
     params = {},
     returns = 'string',
-    signature = 'getcharstr([expr])',
+    signature = 'getcharstr([{expr}])',
   },
   getcmdcompltype = {
     desc = [=[
@@ -7249,7 +7249,7 @@ M.funcs = {
     base = 1,
     desc = [=[
       Return a string that indicates the current mode.
-      If [expr] is supplied and it evaluates to a non-zero Number or
+      If {expr} is supplied and it evaluates to a non-zero Number or
       a non-empty String (|non-zero-arg|), then the full mode is
       returned, otherwise only the first letter is returned.
       Also see |state()|.
@@ -7304,7 +7304,7 @@ M.funcs = {
     ]=],
     name = 'mode',
     params = { { 'expr', 'any' } },
-    signature = 'mode([expr])',
+    signature = 'mode([{expr}])',
   },
   msgpackdump = {
     args = { 1, 2 },