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.

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])

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*

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