vim-patch:9.1.0538: not possible to assign priority when defining a sign (#29592)

Problem:  not possible to assign priority when defining a sign
          (Mathias Fußenegger)
Solution: Add the priority argument for the :sign-define ex command and
          the sign_define() function (LemonBoy)

Use the specified value instead of the default one (SIGN_DEF_PRIO) when
no priority is explicitly specified in sign_place or :sign place.

fixes: vim/vim#8334
closes: vim/vim#15124

https://github.com/vim/vim/commit/b975ddfdf96644b8df808415dee36f99abd48753

Co-authored-by: LemonBoy <thatlemon@gmail.com>

3 files changed, 20 insertions, 12 deletions

diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt
index 180d308ef5..3def778e58 100644
--- a/runtime/doc/builtin.txt
+++ b/runtime/doc/builtin.txt
@@ -7110,6 +7110,7 @@ sign_getdefined([{name}])                                    *sign_getdefined()*
 		   linehl	highlight group used for the whole line the
 				sign is placed in; not present if not set.
 		   name		name of the sign
+		   priority	default priority value of the sign
 		   numhl	highlight group used for the line number where
 				the sign is placed; not present if not set.
 		   text		text that is displayed when there is no icon
@@ -7282,7 +7283,8 @@ sign_placelist({list})                                        *sign_placelist()*
 		    priority	Priority of the sign. When multiple signs are
 				placed on a line, the sign with the highest
 				priority is used. If not specified, the
-				default value of 10 is used. See
+				default value of 10 is used, unless specified
+				otherwise by the sign definition. See
 				|sign-priority| for more information.
 
 		If {id} refers to an existing sign, then the existing sign is
diff --git a/runtime/doc/sign.txt b/runtime/doc/sign.txt
index a64ba0ea1c..9d74f1f376 100644
--- a/runtime/doc/sign.txt
+++ b/runtime/doc/sign.txt
@@ -68,11 +68,12 @@ other plugins using signs.
 
 							*sign-priority*
 Each placed sign is assigned a priority value independently of the sign group.
-The default priority for a sign is 10. When multiple signs that each have an
-icon or text are placed on the same line, signs are ordered with decreasing
-priority from left to right, up until the maximum width set in 'signcolumn'.
-Lower priority signs that do not fit are hidden. Highest priority signs with
-highlight attributes are always shown.
+The default priority for a sign is 10, this value can be changed for different
+signs by specifying a different value at definition time. When multiple signs
+that each have an icon or text are placed on the same line, signs are ordered
+with decreasing priority from left to right, up until the maximum width set in
+'signcolumn'. Low priority signs that do not fit are hidden. Highest priority
+signs with highlight attributes are always shown.
 
 When the line on which the sign is placed is deleted, the sign is removed along
 with it.
@@ -113,6 +114,9 @@ See |sign_define()| for the equivalent Vim script function.
 			toolkit		supports ~
 			Win32		.bmp, .ico, .cur
 
+	priority={prio}
+		Default priority for the sign, see |sign-priority|.
+
 	linehl={group}
 		Highlighting group used for the whole line the sign is placed
 		in.  Most useful is defining a background color.
@@ -183,11 +187,11 @@ See |sign_place()| for the equivalent Vim script function.
 
 		By default, the sign is placed in the global sign group.
 
-		By default, the sign is assigned a default priority of 10. To
-		assign a different priority value, use "priority={prio}" to
-		specify a value.  The priority is used to determine the sign
-		that is displayed when multiple signs are placed on the same
-		line.
+		By default, the sign is assigned a default priority of 10,
+		unless specified otherwise by the sign definition.  To assign a
+		different priority value, use "priority={prio}" to specify a
+		value.  The priority is used to determine the sign that is
+		displayed when multiple signs are placed on the same line.
 
 		Examples: >
 			:sign place 5 line=3 name=sign1 file=a.py
diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua
index 9d4cc825ec..e51041839b 100644
--- a/runtime/lua/vim/_meta/vimfn.lua
+++ b/runtime/lua/vim/_meta/vimfn.lua
@@ -8477,6 +8477,7 @@ function vim.fn.sign_define(list) end
 ---    linehl  highlight group used for the whole line the
 ---     sign is placed in; not present if not set.
 ---    name    name of the sign
+---    priority  default priority value of the sign
 ---    numhl  highlight group used for the line number where
 ---     the sign is placed; not present if not set.
 ---    text    text that is displayed when there is no icon
@@ -8668,7 +8669,8 @@ function vim.fn.sign_place(id, group, name, buf, dict) end
 ---     priority  Priority of the sign. When multiple signs are
 ---     placed on a line, the sign with the highest
 ---     priority is used. If not specified, the
----     default value of 10 is used. See
+---     default value of 10 is used, unless specified
+---     otherwise by the sign definition. See
 ---     |sign-priority| for more information.
 ---
 --- If {id} refers to an existing sign, then the existing sign is