Merge pull request #24820 from zeertzjq/vim-589edb340454

vim-patch:589edb340454,e46a44050562

1 files changed, 21 insertions, 19 deletions

diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt
index 2ce66d8cc2..079052b658 100644
--- a/runtime/doc/builtin.txt
+++ b/runtime/doc/builtin.txt
@@ -2662,7 +2662,7 @@ getmatches([{win}])                                               *getmatches()*
 <
 
 getmousepos()                                                    *getmousepos()*
-		Returns a Dictionary with the last known position of the
+		Returns a |Dictionary| with the last known position of the
 		mouse.  This can be used in a mapping for a mouse click.  The
 		items are:
 			screenrow	screen row
@@ -5741,7 +5741,7 @@ screenchar({row}, {col})                                          *screenchar()*
 		Returns -1 when row or col is out of range.
 
 screenchars({row}, {col})                                        *screenchars()*
-		The result is a List of Numbers.  The first number is the same
+		The result is a |List| of Numbers.  The first number is the same
 		as what |screenchar()| returns.  Further numbers are
 		composing characters on top of the base character.
 		This is mainly to be used for testing.
@@ -5908,7 +5908,7 @@ searchcount([{options}])                                         *searchcount()*
 		without the "S" flag in 'shortmess'.  This works even if
 		'shortmess' does contain the "S" flag.
 
-		This returns a Dictionary. The dictionary is empty if the
+		This returns a |Dictionary|. The dictionary is empty if the
 		previous pattern was not set and "pattern" was not specified.
 
 		  key		type		meaning ~
@@ -5990,7 +5990,7 @@ searchcount([{options}])                                         *searchcount()*
 			" search again
 			call searchcount()
 <
-		{options} must be a Dictionary. It can contain:
+		{options} must be a |Dictionary|. It can contain:
 		  key		type		meaning ~
 		  recompute	|Boolean|	if |TRUE|, recompute the count
 						like |n| or |N| was executed.
@@ -7374,28 +7374,30 @@ state([{what}])                                                        *state()*
 		current state.  Mostly useful in callbacks that want to do
 		work that may not always be safe.  Roughly this works like:
 		- callback uses state() to check if work is safe to do.
-		  If yes, then do it right away.
-		  Otherwise add to work queue and add SafeState autocommand.
-		- When SafeState is triggered, check with state() if the work
-		  can be done now, and if yes remove it from the queue and
-		  execute.
+		  Yes: then do it right away.
+		  No:  add to work queue and add a |SafeState| autocommand.
+		- When SafeState is triggered and executes your autocommand,
+		  check with `state()` if the work can be done now, and if yes
+		  remove it from the queue and execute.
+		  Remove the autocommand if the queue is now empty.
 		Also see |mode()|.
 
 		When {what} is given only characters in this string will be
 		added.  E.g, this checks if the screen has scrolled: >vim
-			if state('s') != ''
+			if state('s') == ''
+			   " screen has not scrolled
 
 		These characters indicate the state, generally indicating that
 		something is busy:
-		    m  halfway a mapping, :normal command, feedkeys() or
-		       stuffed command
-		    o  operator pending or waiting for a command argument
-		    a  Insert mode autocomplete active
-		    x  executing an autocommand
-		    S  not triggering SafeState
-		    c  callback invoked, including timer (repeats for
-		       recursiveness up to "ccc")
-		    s  screen has scrolled for messages
+		    m	halfway a mapping, :normal command, feedkeys() or
+			stuffed command
+		    o	operator pending, e.g. after |d|
+		    a	Insert mode autocomplete active
+		    x	executing an autocommand
+		    S	not triggering SafeState, e.g. after |f| or a count
+		    c	callback invoked, including timer (repeats for
+			recursiveness up to "ccc")
+		    s	screen has scrolled for messages
 
 stdioopen({opts})                                                  *stdioopen()*
 		With |--headless| this opens stdin and stdout as a |channel|.