diff --git a/.gitignore b/.gitignore new file mode 100644 index 00000000..926ccaaf --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +doc/tags diff --git a/CHANGELOG.md b/CHANGELOG.md index 162f8255..aa4bd313 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,10 +1,11 @@ -# 0.2.4-dev +# 0.2.4 - Bug Fix: Handle completion items with empty detail. - `LSClientShowHover` now reuses the window it already opened rather than closing it and splitting again to allow for maintaining layout. - Add optional configuration `g:lsc_preview_split_direction` to override `splitbelow`. +- Add docs. # 0.2.3 diff --git a/doc/lsc.txt b/doc/lsc.txt new file mode 100644 index 00000000..20653050 --- /dev/null +++ b/doc/lsc.txt @@ -0,0 +1,155 @@ +*lsc* Language Server Client + +INTRODUCTION *lsc-intro* + +vim-lsc communicates with a server following the Language Server Protocol and +adds autocomplete, diagnostic highlighting, and reference searching. + +vim-lsc does not have any built-in support for any language, all features are +enabled through languag specific servers and should work with any server +following the protocol. Each feature is dependent on support in the configured +server. + +https://github.com/natebosch/vim-lsc + +SETUP *lsc-setup* + +There is no install step for vim-lsc. Configure the filetypes that are tracked +by installed language servers in the variable "g:lsc_server_commands". Each +value in this dict should be a string which corresponds to an executable in +your "$PATH". If multiple filetypes are tracked by the same server they should +be entered as separate keys with the same value. For example: +> + let g:lsc_server_commands = { + \ 'dart': 'dart_language_server', + \ 'html': 'dart_language_server', + \} +< + +lsc will communicate with each executable over stdin/stdout following the +RPC protocol as specified. +> + +COMMANDS *lsc-commands* + + *:LSClientGoToDefinition* +Jump to the location defining the element under the cursor. Sends a +"textDocument/definition" request with the location set to the cursor's +position. If the cursor is not in the same position when the server responds +the jump will be canceled. With |lsc-default-map| this command is bound to + + + *:LSClientFindReferences* +Populate the |quickfix| with a list of location which reference the element +under the cursor, including it's definition. Sends a "textDocument/references" +request with the location set to the cursor's position. With +|lsc-default-map| this command is bound to "gr". + + *:LSClientShowHover* +Open a |preview| window with hover information corresponding to the element +under the cursor. Sends a "textDocument/hover" request with the location set +to the cursor's position. If there is no hover information will show a message +without opening the preview window. With |lsc-default-map| this command is +bound to "K". + +If the preview window is already visible it will reuse it and maintain layout, +resizing it only if it is smaller than both |previewheight| and the size of +The new hover information. + +If the preview window is not visible it will |split| the window and size it no +bigger than |previewheight|. Override the direction of the split by setting +"g:lsc_preview_split_direction" to either |above| or |below|. + + *:LSClientRestartServer* +Sends requests to the server for the current filetype to "shutdown" and +"exit", and after the process exits, restarts it. If the server is +unresponsive to these requests it will need to be killed manually. + + *:LSClientDisable* +Sends requests to the server for the current filetype to "shutdown" and +"exit", and ignores further changes in these files. + + *:LSClientEnable* +If the server was previously disabled, restart the server and re-enable change +tracking for the current filetype. + +CONFIGURATION *lsc-configure* + + *lsc-configure-trace* +Set the "trace" field sent to the server during initialization using the +"g:lsc_trace_level". Valid values are "off", "messages", or "verbose". +Defaults to "off". Generally this field configures logging in the server. + + *lsc-configure-complete* +To disable the built-in autocompletion set "g:lsc_enable_autocomplete" to +"v:false". Requests for completions will still be sent to the server, but the +response will not open the popupmenu or complete words. Set |completefunc| or +|omnifunc| to "lsc#complete#complete" to manually trigger completion on demand. +The function will have no completions if it is not made in a position where +autocomplete would have shown suggestions, or if the server has not responded +with results before completion is started. + +The completefunc can be automatically set for buffers with files tracked by a +langage server by setting the "Complete" key in |g:lsc_auto_map|. + +Note: By default |completeopt| includes "preview" which will open the preview +window to show more details for selected completion items. Close the window +after completion with CTRL_W-z or disable with "set completeopt-=preview". To +automatically close the preview window after completion use the following: +> + autocmd CompleteDone * silent! pclose +< + + *lsc-configure-hover* +By default the `:LSClientShowHover` command splits the window following +the setting |splitbelow|. Override the direction that the hover preview splits +with "g:lsc_preview_split_direction" set to either |above| or |below|. This +configuration will not impact the preview window which may open during +completion. + + *lsc-configure-highlight* +vim-lsc uses the highlight groups "lscDiagnosticError", +"lscDiagnosticWarning", "lscDiagnosticInfo", and "lscDiagnosticHint". By +default "lscDiagnosticError" is linked to |hl-Error|, and the rest are linked +to |hl-SpellBad|. Override this by setting or linking any of these highlight +groups. For example: +> + highlight lscDiagnosticError ctermbg=160 + highlight link lscDiagnosticWarning SpellCap +< + + *g:lsc_auto_map* +If you want to overload keymaps to operate specifically when vim-lsc is +enabled for a buffer set the variable "g:lsc_auto_map". Set the value to +"v:true" to use the defaults |vim-lsc-default-map|, or set to a dict to use +other keys, or to only map a subset of the commands. The available keys +correspond to command names - "GoToDefinition", "FindReferences", and +"ShowHover". Additionally the key "Completion" can choose a completefunc to +set to the vim-lsc completion function, this will only have effect if +"g:lsc_enable_autocomplete" is "v:false". + + *lsc-default-map* +The default mapping for keys, if you've opted in to "g:lsc_auto_map" are: + + `:LSClientGoToDefinition` +gr `:LSClientFindReferences` +K `:LSClientShowHover` + +If "g:lsc_enable_autocomplete" is set to "v:false" then |completefunc| will be +set to the vim-lsc completion function. + +DEBUGGING TIPS *lsc-debugging* + +If you are having difficulty with integration with a particular language +server, you can spy into the communication with the server by wrapping it in a +script to log stdin and stdout. For example if the server is normally started +with "my_language_server", write a script like "my_languag_server_logged.sh" +and point "g:lsc_server_commands" at this script. +> + #!/bin/bash + tee in.log | my_language_server | tee out.log +< +If a language server is following the protocol but does not work with vim-lsc, +file an issue at https://github.com/natebosch/vim-lsc/issues + + vim:tw=78:sw=4:ts=8:ft=help:norl: