feat(signs)!: place higher-priority signs from the left #27781

Problem:
Higher-priority signs may be hidden by lower-priority signs.

Solution:
Place higher-priority signs from the left.

Example:

    nvim_buf_set_extmark(0, ns, 0, -1, {sign_text='H', priority=1})
    nvim_buf_set_extmark(0, ns, 0, -1, {sign_text='W', priority=2})
    nvim_buf_set_extmark(0, ns, 0, -1, {sign_text='E', priority=3})

Before:

            |     |
          H | W E |
          ^ |     |
Not visible

After:

  |     |
  | E W | H
  |     | ^
          Not visible

Fixes #16632

2 files changed, 5 insertions, 4 deletions

diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt
index 0730faa441..f8bc983441 100644
--- a/runtime/doc/news.txt
+++ b/runtime/doc/news.txt
@@ -38,7 +38,7 @@ DEFAULTS
 
 EDITOR
 
-• TODO
+• The order in which signs are placed was changed. Higher priority signs will now appear left of lower priority signs.
 
 EVENTS
 
diff --git a/runtime/doc/sign.txt b/runtime/doc/sign.txt
index 0360ce67f6..6fa260be40 100644
--- a/runtime/doc/sign.txt
+++ b/runtime/doc/sign.txt
@@ -72,9 +72,10 @@ on the same line, the attributes of the sign with the highest priority is used
 independently of the sign group. The default priority for a sign is 10. The
 priority is assigned at the time of placing a sign.
 
-When two signs with the same priority are present, and one has an icon or text
-in the signcolumn while the other has line highlighting, then both are
-displayed.
+When multiple signs that each have an icon or text are present, signs are
+ordered with increasing 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.
 
 When the line on which the sign is placed is deleted, the sign is removed along
 with it.