Show a single virtualtext message by default

Show only a single virtualtext message per line by default. The setting
can be configured to whatever the user wants. This default prevents
several linters from spamming the editor with messages that run off into
the right margin.

Documentation now clarifies that problems have a predictable order, and
which message will come first.

3 files changed, 27 insertions, 6 deletions

diff --git a/autoload/ale/virtualtext.vim b/autoload/ale/virtualtext.vim
index 72bc8e6f..1f4d1fde 100644
--- a/autoload/ale/virtualtext.vim
+++ b/autoload/ale/virtualtext.vim
@@ -31,7 +31,8 @@ let g:ale_virtualtext_delay = get(g:, 'ale_virtualtext_delay', 10)
 " Controls the positioning of virtualtext
 let g:ale_virtualtext_column = get(g:, 'ale_virtualtext_column', 0)
 let g:ale_virtualtext_maxcolumn = get(g:, 'ale_virtualtext_maxcolumn', 0)
-let g:ale_virtualtext_single = get(g:,'ale_virtualtext_single',0)
+" If 1, only show the first problem with virtualtext.
+let g:ale_virtualtext_single = get(g:, 'ale_virtualtext_single', 1)
 
 let s:cursor_timer = get(s:, 'cursor_timer', -1)
 let s:last_pos = get(s:, 'last_pos', [0, 0, 0])
diff --git a/doc/ale.txt b/doc/ale.txt
index dff7ffa0..2b73337c 100644
--- a/doc/ale.txt
+++ b/doc/ale.txt
@@ -2434,16 +2434,18 @@ g:ale_virtualtext_maxcolumn                       *g:ale_virtualtext_maxcolumn*
 g:ale_virtualtext_single                             *g:ale_virtualtext_single*
                                                      *b:ale_virtualtext_single*
   Type: |Number|
-  Default: `0`
+  Default: `1`
 
   This setting has no effect when |g:ale_use_neovim_diagnostics_api| is `1`.
 
-  Enable or disable concatenation of multiple virtualtext messages on a single
-  line.  By default, if a line has multiple errors or warnings, each will be
+  Enable or disable concatenation of multiple virtual text messages on a single
+  line. By default, if a line has multiple errors or warnings, each will be
   appended in turn.
 
-  With `single` set to a non-zero value, only the first message appears.
-  (No attempt is made to prefer message types such as errors over warnings)
+  With `single` set to a non-zero value, only the first problem on a line will
+  be printed with virtual text. The problem at the left-most position on a
+  line will be printed. If two problems exist at the same position, the most
+  severe problem will be printed.
 
 
 g:ale_virtualenv_dir_names                         *g:ale_virtualenv_dir_names*
diff --git a/test/test_virtualtext.vader b/test/test_virtualtext.vader
index 40a2b749..25965f50 100644
--- a/test/test_virtualtext.vader
+++ b/test/test_virtualtext.vader
@@ -2,6 +2,7 @@ Before:
   Save g:ale_buffer_info
   Save g:ale_virtualtext_cursor
   Save g:ale_virtualtext_delay
+  Save g:ale_virtualtext_single
   Save g:ale_virtualtext_prefix
   Save b:ale_virtualtext_prefix
   Save g:ale_use_neovim_diagnostics_api
@@ -9,7 +10,9 @@ Before:
   call ale#virtualtext#ResetDataForTests()
 
   let g:setting = ''
+  let g:ale_virtualtext_prefix = '%comment% %type%: '
   let g:ale_virtualtext_delay = 0
+  let g:ale_virtualtext_single = 0
   let g:ale_buffer_info = {
   \ bufnr(''): {
   \   'loclist': [
@@ -167,6 +170,21 @@ Execute(We should set errors across all lines):
     endif
   endif
 
+Execute(We should be able to limit virtual messages to the first one only):
+  let g:ale_virtualtext_single = 1
+
+  if has('patch-9.0.0297') || has('nvim-0.8.0')
+    call ale#virtualtext#SetTexts(bufnr(''), g:ale_buffer_info[bufnr('')].loclist)
+
+    AssertEqual '# W: Line 2 warning 1', ale#virtualtext#GetLastMessageForTests()
+
+    if has('patch-9.0.0297')
+      AssertEqual ['ALEVirtualTextError'], map(prop_list(1), {_, v -> v.type})
+      AssertEqual ['ALEVirtualTextWarning'],
+      \ map(prop_list(2), {_, v -> v.type})
+    endif
+  endif
+
 Execute(We should not set cursor messages when Neovim diagnostics are enabled):
   let g:ale_use_neovim_diagnostics_api = 1