#1428 Show multiline hover messages, and document the new command

5 files changed, 48 insertions, 12 deletions

diff --git a/README.md b/README.md
index 066d6eb9..dc397d05 100644
--- a/README.md
+++ b/README.md
@@ -28,6 +28,7 @@ formatting tools, and some Language Server Protocol and `tsserver` features.
     3. [Completion](#usage-completion)
     4. [Go To Definition](#usage-go-to-definition)
     5. [Find References](#usage-find-references)
+    6. [Hovering](#usage-hover)
 3. [Installation](#installation)
     1. [Installation with Vim package management](#standard-installation)
     2. [Installation with Pathogen](#installation-with-pathogen)
@@ -250,6 +251,15 @@ ALE supports finding references for words under your cursor with the
 
 See `:help ale-find-references` for more information.
 
+<a name="usage-hover"></a>
+
+### 2.vi Hovering
+
+ALE supports "hover" information for printing brief information about symbols
+at the cursor taken from LSP linters with the `ALEHover` command.
+
+See `:help ale-hover` for more information.
+
 <a name="installation"></a>
 
 ## 3. Installation
diff --git a/autoload/ale/hover.vim b/autoload/ale/hover.vim
index fdae350e..2ccc4ff0 100644
--- a/autoload/ale/hover.vim
+++ b/autoload/ale/hover.vim
@@ -62,12 +62,7 @@ function! ale#hover#HandleLSPResponse(conn_id, response) abort
             let l:str = substitute(l:str, '^\s*\(.\{-}\)\s*$', '\1', '')
 
             if !empty(l:str)
-                " Compress multi-line hover messages into one line.
-                let l:str = substitute(l:str, "\n", ' ', 'g')
-                let l:str = substitute(l:str, ' \+', ' ', 'g')
-                let l:str = substitute(l:str, '^\s*\(.\{-}\)\s*$', '\1', '')
-
-                call ale#util#Echo(l:str)
+                call ale#util#ShowMessage(l:str)
             endif
         endif
     endif
diff --git a/autoload/ale/util.vim b/autoload/ale/util.vim
index d0dbec65..4e789b72 100644
--- a/autoload/ale/util.vim
+++ b/autoload/ale/util.vim
@@ -11,9 +11,18 @@ function! ale#util#FeedKeys(...) abort
     return call('feedkeys', a:000)
 endfunction
 
-" A wrapper function for echo so we can test calls for it.
-function! ale#util#Echo(string) abort
-    execute 'echo a:string'
+" Show a message in as small a window as possible.
+"
+" Vim 8 does not support echoing long messages from asynchronous callbacks,
+" but NeoVim does. Small messages can be echoed in Vim 8, and larger messages
+" have to be shown in preview windows.
+function! ale#util#ShowMessage(string) abort
+    " We have to assume the user is using a monospace font.
+    if has('nvim') || (a:string !~? "\n" && len(a:string) < &columns)
+        execute 'echo a:string'
+    else
+        call ale#preview#Show(split(a:string, "\n"))
+    endif
 endfunction
 
 " A wrapper function for execute, so we can test executing some commands.
diff --git a/doc/ale.txt b/doc/ale.txt
index d5e6958b..45d7ba1a 100644
--- a/doc/ale.txt
+++ b/doc/ale.txt
@@ -654,6 +654,15 @@ supported:
 |ALEFindReferences| - Find references for the word under the cursor.
 
 
+-------------------------------------------------------------------------------
+5.4 Hovering                                                        *ale-hover*
+
+ALE supports "hover" information for printing brief information about symbols
+at the cursor taken from LSP linters. The following commands are supported:
+
+|ALEHover| - Print information about the symbol at the cursor.
+
+
 ===============================================================================
 6. Global Options                                                 *ale-options*
 
@@ -1806,6 +1815,19 @@ ALEGoToDefinitionInTab                                 *ALEGoToDefinitionInTab*
   A plug mapping `<Plug>(ale_go_to_definition_in_tab)` is defined for this
   command.
 
+
+ALEHover                                                             *ALEHover*
+
+  Print brief information about the symbol under the cursor, taken from any
+  available LSP linters. There may be a small non-blocking delay before
+  information is printed.
+
+  NOTE: In Vim 8, long messages will be shown in a preview window, as Vim 8
+  does not support showing a prompt to press enter to continue for long
+  messages from asynchronous callbacks.
+
+  A plug mapping `<Plug>(ale_hover)` is defined for this command.
+
                                                                      *:ALELint*
 ALELint                                                               *ALELint*
 
diff --git a/test/test_hover.vader b/test/test_hover.vader
index 57734b4e..3018249d 100644
--- a/test/test_hover.vader
+++ b/test/test_hover.vader
@@ -26,7 +26,7 @@ Before:
     return 42
   endfunction
 
-  function! ale#util#Echo(string) abort
+  function! ale#util#ShowMessage(string) abort
       call add(g:echo_list, a:string)
   endfunction
 
@@ -94,7 +94,7 @@ Execute(LSP hover response with lists of strings should be handled):
   \  "bar\n",
   \]})
 
-  AssertEqual ['foo bar'], g:echo_list
+  AssertEqual ["foo\n\nbar\n"], g:echo_list
   AssertEqual {}, ale#hover#GetMap()
 
 Execute(LSP hover response with lists of strings and marked strings should be handled):
@@ -103,5 +103,5 @@ Execute(LSP hover response with lists of strings and marked strings should be ha
   \  "bar\n",
   \]})
 
-  AssertEqual ['foo bar'], g:echo_list
+  AssertEqual ["foo\nbar\n"], g:echo_list
   AssertEqual {}, ale#hover#GetMap()