vim-patch:8.1.0697: ":sign place" requires the buffer argument

Problem:    ":sign place" requires the buffer argument.
Solution:   Make the argument optional.  Also update the help and clean up the
            sign test. (Yegappan Lakshmanan, closes vim/vim#3767)
https://github.com/vim/vim/commit/b328cca2548936c5f68fff683049a929882f5011

2 files changed, 44 insertions, 18 deletions

diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt
index 028a4e9b7a..c56e4cdef2 100644
--- a/runtime/doc/eval.txt
+++ b/runtime/doc/eval.txt
@@ -3581,20 +3581,24 @@ extend({expr1}, {expr2} [, {expr3}])			*extend()*
 feedkeys({string} [, {mode}])				*feedkeys()*
 		Characters in {string} are queued for processing as if they
 		come from a mapping or were typed by the user.
+
 		By default the string is added to the end of the typeahead
 		buffer, thus if a mapping is still being executed the
 		characters come after them.  Use the 'i' flag to insert before
 		other characters, they will be executed next, before any
 		characters from a mapping.
+
 		The function does not wait for processing of keys contained in
 		{string}.
+
 		To include special keys into {string}, use double-quotes
 		and "\..." notation |expr-quote|. For example,
 		feedkeys("\<CR>") simulates pressing of the <Enter> key. But
 		feedkeys('\<CR>') pushes 5 characters.
-		If {mode} is absent, keys are remapped.
+
 		{mode} is a String, which can contain these character flags:
-		'm'	Remap keys. This is default.
+		'm'	Remap keys. This is default.  If {mode} is absent,
+			keys are remapped.
 		'n'	Do not remap keys.
 		't'	Handle keys as if typed; otherwise they are handled as
 			if coming from a mapping.  This matters for undo,
@@ -3608,6 +3612,9 @@ feedkeys({string} [, {mode}])				*feedkeys()*
 			will behave as if <Esc> is typed, to avoid getting
 			stuck, waiting for a character to be typed before the
 			script continues.
+			Note that if you manage to call feedkeys() while
+			executing commands, thus calling it recursively, the
+			all typehead will be consumed by the last call.
 		'!'	When used with 'x' will not end Insert mode. Can be
 			used in a test when a timer is set to exit Insert mode
 			a little later.  Useful for testing CursorHoldI.
@@ -7378,6 +7385,9 @@ sign_define({name} [, {dict}])				*sign_define()*
 				associated line. Overrides |hl-LineNr|,
 				|hl-CursorLineNr|.
 
+		If the sign named {name} already exists, then the attributes
+		of the sign are updated.
+
 		Returns 0 on success and -1 on failure.
 
 		Examples: >
@@ -7432,6 +7442,7 @@ sign_getplaced([{expr} [, {dict}]])			*sign_getplaced()*
 		empty string, then only signs in the global group are
 		returned.  If no arguments are supplied, then signs in the
 		global group placed in all the buffers are returned.
+		See |sign-group|.
 
 		Each list item in the returned value is a dictionary with the
 		following entries:
@@ -7447,7 +7458,8 @@ sign_getplaced([{expr} [, {dict}]])			*sign_getplaced()*
 			name	name of the defined sign
 			priority	sign priority
 
-		Returns an empty list on failure.
+		Returns an empty list on failure or if there are no placed
+		signs.
 
 		Examples: >
 			" Get a List of signs placed in eval.c in the
@@ -7480,7 +7492,8 @@ sign_place({id}, {group}, {name}, {expr} [, {dict}])
 		allocated.  Otherwise the specified number is used. {group} is
 		the sign group name. To use the global sign group, use an
 		empty string.  {group} functions as a namespace for {id}, thus
-		two groups can use the same IDs.
+		two groups can use the same IDs. Refer to |sign-identifier|
+		for more information.
 		
 		{name} refers to a defined sign.
 		{expr} refers to a buffer name or number. For the accepted
@@ -8576,7 +8589,7 @@ undofile({name})					*undofile()*
 		If {name} is empty undofile() returns an empty string, since a
 		buffer without a file name will not write an undo file.
 		Useful in combination with |:wundo| and |:rundo|.
-		When compiled without the +persistent_undo option this always
+		When compiled without the |+persistent_undo| option this always
 		returns an empty string.
 
 undotree()						*undotree()*
diff --git a/runtime/doc/sign.txt b/runtime/doc/sign.txt
index 4b9c64e575..cbc3a19399 100644
--- a/runtime/doc/sign.txt
+++ b/runtime/doc/sign.txt
@@ -46,13 +46,23 @@ Example to set the color: >
 
 	:highlight SignColumn guibg=darkgrey
 <
+							*sign-identifier*
+Each placed sign is identified by a number called the sign identifier. This
+identifier is used to jump to the sign or to remove the sign. The identifier
+is assigned when placing the sign using the |sign-place| command or the
+|sign_place()| function. Each sign identifier should be a unique number. If
+multiple placed signs use the same identifier, then jumping to or removing a
+sign becomes unpredictable. To avoid overlapping identifiers, sign groups can
+be used. The |sign_place()| function can be called with a zero sign identifier
+to allocate the next available identifier.
+
 							*sign-group*
-Each sign can be assigned to either the global group or a named group. When
-placing a sign, if a group name is not supplied, or an empty string is used,
-then the sign is placed in the global group. Otherwise the sign is placed in
-the named group. The sign identifier is unique within a group. The sign group
-allows Vim plugins to use unique signs without interfering with other plugins
-using signs.
+Each placed sign can be assigned to either the global group or a named group.
+When placing a sign, if a group name is not supplied, or an empty string is
+used, then the sign is placed in the global group. Otherwise the sign is
+placed in the named group. The sign identifier is unique within a group. The
+sign group allows Vim plugins to use unique signs without interfering with
+other plugins using signs.
 
 							*sign-priority*
 Each placed sign is assigned a priority value. When multiple signs are placed
@@ -171,8 +181,9 @@ See |sign_place()| for the equivalent Vim script function.
 			:sign place 9 group=g2 priority=50 line=5
 							\ name=sign1 file=a.py
 <
-:sign place {id} line={lnum} name={name} buffer={nr}
-		Same, but use buffer {nr}.
+:sign place {id} line={lnum} name={name} [buffer={nr}]
+		Same, but use buffer {nr}.  If the buffer argument is not
+		given, place the sign in the current buffer.
 
 							*E885*
 :sign place {id} name={name} file={fname}
@@ -184,8 +195,9 @@ See |sign_place()| for the equivalent Vim script function.
 		The optional "group={group}" attribute can be used before
 		"file=" to select a sign in a particular group.
 
-:sign place {id} name={name} buffer={nr}
-		Same, but use buffer {nr}.
+:sign place {id} name={name} [buffer={nr}]
+		Same, but use buffer {nr}.  If the buffer argument is not
+		given, use the current buffer.
 
 
 REMOVING SIGNS						*:sign-unplace* *E159*
@@ -307,11 +319,12 @@ JUMPING TO A SIGN					*:sign-jump* *E157*
 :sign jump {id} group={group} file={fname}
 		Same but jump to the sign in group {group}
 
-:sign jump {id} buffer={nr}					*E934*
+:sign jump {id} [buffer={nr}]					*E934*
 		Same, but use buffer {nr}.  This fails if buffer {nr} does not
-		have a name.
+		have a name. If the buffer argument is not given, use the
+		current buffer.
 
-:sign jump {id} group={group} buffer={nr}
+:sign jump {id} group={group} [buffer={nr}]
 		Same but jump to the sign in group {group}