Merge branch 'master' into dont-clear-screen-syntax

README.md

@@ -1931,6 +1931,11 @@ See the [file type feature summary](#quick-feature-summary) for an overview of
 the features available for each file type. See the _YcmCompleter subcommands_
 section for more information on the available subcommands and their usage.
 
+Some commands, like `Format` accept a range, like `:%YcmCompleter Format`.
+
+Some commands like `GetDoc` and the various `GoTo` commands respect modifiers,
+like `:rightbelow YcmCompleter GetDoc`, `:vertical YcmCompleter GoTo`.
+
 YcmCompleter Subcommands
 ------------------------
 
@@ -2147,6 +2152,27 @@ under the cursor. Depending on the file type, this includes things like:
 * Python docstrings,
 * etc.
 
+The documentation is opened in the preview window, and options like
+`previewheight` are respected. If you would like to customise the height and
+position of this window, we suggest a custom command that:
+
+* Sets `previewheight` temporarily
+* Runs the `GetDoc` command with supplied modifiers
+* Restores `previewheight`.
+
+For example:
+
+```viml
+command -count ShowDocWithSize
+  \ let g:ph=&previewheight 
+  \ <bar> set previewheight=<count>
+  \ <bar> <mods> YcmCompleter GetDoc
+  \ <bar> let &previewheight=g:ph
+```
+
+You can then use something like `:botright vertical 80ShowDocWithSize`. Here's an
+example of that: https://asciinema.org/a/hE6Pi1gU6omBShwFna8iwGEe9
+
 Supported in filetypes: `c, cpp, objc, objcpp, cuda, cs, go, java, javascript,
 python, typescript, rust`
 

doc/youcompleteme.txt

@@ -2182,6 +2182,11 @@ See the file type feature summary for an overview of the features available for
 each file type. See the _YcmCompleter subcommands_ section for more information
 on the available subcommands and their usage.
 
+Some commands, like |Format| accept a range, like ':%YcmCompleter Format'.
+
+Some commands like |GetDoc| and the various |GoTo| commands respect modifiers,
+like ':rightbelow YcmCompleter GetDoc', ':vertical YcmCompleter GoTo'.
+
 -------------------------------------------------------------------------------
                                        *youcompleteme-ycmcompleter-subcommands*
 YcmCompleter Subcommands ~
@@ -2418,6 +2423,25 @@ under the cursor. Depending on the file type, this includes things like:
 - Python docstrings,
 - etc.
 
+The documentation is opened in the preview window, and options like
+'previewheight' are respected. If you would like to customise the height and
+position of this window, we suggest a custom command that:
+
+- Sets 'previewheight' temporarily
+- Runs the |GetDoc| command with supplied modifiers
+- Restores 'previewheight'.
+
+For example:
+>
+  command -count ShowDocWithSize
+    \ let g:ph=&previewheight 
+    \ <bar> set previewheight=<count>
+    \ <bar> <mods> YcmCompleter GetDoc
+    \ <bar> let &previewheight=g:ph
+<
+You can then use something like ':botright vertical 80ShowDocWithSize'. Here's
+an example of that: https://asciinema.org/a/hE6Pi1gU6omBShwFna8iwGEe9
+
 Supported in filetypes: 'c, cpp, objc, objcpp, cuda, cs, go, java, javascript,
 python, typescript, rust'
 

python/ycm/client/command_request.py

@@ -93,7 +93,7 @@ class CommandRequest( BaseRequest ):
       return self._HandleMessageResponse()
 
     if 'detailed_info' in self._response:
-      return self._HandleDetailedInfoResponse()
+      return self._HandleDetailedInfoResponse( modifiers )
 
     # The only other type of response we understand is GoTo, and that is the
     # only one that we can't detect just by inspecting the response (it should
@@ -201,8 +201,9 @@ class CommandRequest( BaseRequest ):
     vimsupport.PostVimMessage( self._response[ 'message' ], warning = False )
 
 
-  def _HandleDetailedInfoResponse( self ):
-    vimsupport.WriteToPreviewWindow( self._response[ 'detailed_info' ] )
+  def _HandleDetailedInfoResponse( self, modifiers ):
+    vimsupport.WriteToPreviewWindow( self._response[ 'detailed_info' ],
+                                     modifiers )
 
 
 def SendCommandRequestAsync( arguments, extra_data = None, silent = True ):

python/ycm/tests/client/command_request_test.py

@@ -283,7 +283,7 @@ class Response_Detection_Test( TestCase ):
         request = CommandRequest( [ command ] )
         request._response = { 'detailed_info': info }
         request.RunPostCommandActionsIfNeeded( 'topleft' )
-        write_to_preview.assert_called_with( info )
+        write_to_preview.assert_called_with( info, 'topleft' )
 
     for command, info in [
       [ '___________', 'This is a message' ],

python/ycm/tests/vimsupport_test.py

@@ -1375,7 +1375,7 @@ class VimsupportTest( TestCase ):
   def test_WriteToPreviewWindow( self, vim_current, vim_command ):
     vim_current.window.options.__getitem__ = MagicMock( return_value = True )
 
-    vimsupport.WriteToPreviewWindow( "test" )
+    vimsupport.WriteToPreviewWindow( "test", '' )
 
     vim_command.assert_has_exact_calls( [
       call( 'silent! pclose!' ),
@@ -1398,11 +1398,39 @@ class VimsupportTest( TestCase ):
       call( 'readonly', True ),
     ], any_order = True )
 
+  @patch( 'vim.command', new_callable=ExtendedMock )
+  @patch( 'vim.current', new_callable=ExtendedMock )
+  def test_WriteToPreviewWindow_Mods( self, vim_current, vim_command ):
+    vim_current.window.options.__getitem__ = MagicMock( return_value = True )
+
+    vimsupport.WriteToPreviewWindow( "test", 'tab leftabove' )
+
+    vim_command.assert_has_exact_calls( [
+      call( 'silent! pclose!' ),
+      call( 'silent! tab leftabove pedit! _TEMP_FILE_' ),
+      call( 'silent! wincmd P' ),
+      call( 'silent! wincmd p' ) ] )
+
+    vim_current.buffer.__setitem__.assert_called_with(
+        slice( None, None, None ), [ 'test' ] )
+
+    vim_current.buffer.options.__setitem__.assert_has_exact_calls( [
+      call( 'modifiable', True ),
+      call( 'readonly', False ),
+      call( 'buftype', 'nofile' ),
+      call( 'bufhidden', 'wipe' ),
+      call( 'buflisted', False ),
+      call( 'swapfile', False ),
+      call( 'modifiable', False ),
+      call( 'modified', False ),
+      call( 'readonly', True ),
+    ], any_order = True )
+
 
   @patch( 'vim.current' )
   def test_WriteToPreviewWindow_MultiLine( self, vim_current ):
     vim_current.window.options.__getitem__ = MagicMock( return_value = True )
-    vimsupport.WriteToPreviewWindow( "test\ntest2" )
+    vimsupport.WriteToPreviewWindow( "test\ntest2", '' )
 
     vim_current.buffer.__setitem__.assert_called_with(
         slice( None, None, None ), [ 'test', 'test2' ] )
@@ -1413,7 +1441,7 @@ class VimsupportTest( TestCase ):
   def test_WriteToPreviewWindow_JumpFail( self, vim_current, vim_command ):
     vim_current.window.options.__getitem__ = MagicMock( return_value = False )
 
-    vimsupport.WriteToPreviewWindow( "test" )
+    vimsupport.WriteToPreviewWindow( "test", '' )
 
     vim_command.assert_has_exact_calls( [
       call( 'silent! pclose!' ),
@@ -1434,7 +1462,7 @@ class VimsupportTest( TestCase ):
 
     vim_current.window.options.__getitem__ = MagicMock( return_value = False )
 
-    vimsupport.WriteToPreviewWindow( "test\ntest2" )
+    vimsupport.WriteToPreviewWindow( "test\ntest2", '' )
 
     vim_command.assert_has_exact_calls( [
       call( 'silent! pclose!' ),

python/ycm/vimsupport.py

@@ -1231,12 +1231,14 @@ def JumpToTab( tab_number ):
   vim.command( f'silent! tabn { tab_number }' )
 
 
-def OpenFileInPreviewWindow( filename ):
+def OpenFileInPreviewWindow( filename, modifiers ):
   """ Open the supplied filename in the preview window """
-  vim.command( 'silent! pedit! ' + filename )
+  if modifiers:
+    modifiers = ' ' + modifiers
+  vim.command( f'silent!{modifiers} pedit! { filename }' )
 
 
-def WriteToPreviewWindow( message ):
+def WriteToPreviewWindow( message, modifiers ):
   """ Display the supplied message in the preview window """
 
   # This isn't something that comes naturally to Vim. Vim only wants to show
@@ -1248,7 +1250,7 @@ def WriteToPreviewWindow( message ):
 
   ClosePreviewWindow()
 
-  OpenFileInPreviewWindow( vim.eval( 'tempname()' ) )
+  OpenFileInPreviewWindow( vim.eval( 'tempname()' ), modifiers )
 
   if JumpToPreviewWindow():
     # We actually got to the preview window. By default the preview window can't