diff --git a/README.md b/README.md index 633f388..c1b6d43 100644 --- a/README.md +++ b/README.md @@ -10,17 +10,14 @@ Readme! 1. There is a Github issue that documents [breaking changes](https://github.com/hrsh7th/nvim-cmp/issues/231) for nvim-cmp. Subscribe to the issue to be notified of upcoming breaking changes. 2. This is my hobby project. You can support me via GitHub sponsors. -3. Bug reports are welcome, but I might not fix if you don't provide a minimal reproduction configuration and steps. -4. The nvim-cmp documents is [here](./doc/cmp.txt). -5. The nvim-cmp is designed for `customization`! It's not designed to `work out of the box`. - +3. Bug reports are welcome, but don't expect a fix unless you provide minimal configuration and steps to reproduce your issue. Concept ==================== - Full support for LSP completion related capabilities - Powerful customizability via Lua functions -- Smart handling of key mapping +- Smart handling of key mappings - No flicker @@ -29,7 +26,7 @@ Setup ### Recommended Configuration -This example configuration uses `vim-plug` as the plugin manager and `vim-vsnip` as snippet plugin. +This example configuration uses `vim-plug` as the plugin manager and `vim-vsnip` as a snippet plugin. ```lua call plug#begin(s:plug_dir) @@ -135,12 +132,9 @@ EOF ### Where can I find more completion sources? -- See the [Wiki](https://github.com/hrsh7th/nvim-cmp/wiki/List-of-sources) -- See the [GitHub topic](https://github.com/topics/nvim-cmp). +Have a look at the [Wiki](https://github.com/hrsh7th/nvim-cmp/wiki/List-of-sources) and the `nvim-cmp` [GitHub topic](https://github.com/topics/nvim-cmp). ### Where can I find advanced configuration examples? -See the [Wiki](https://github.com/hrsh7th/nvim-cmp/wiki) - - +See the [Wiki](https://github.com/hrsh7th/nvim-cmp/wiki). diff --git a/doc/cmp.txt b/doc/cmp.txt index 8bc5aa8..85207d2 100644 --- a/doc/cmp.txt +++ b/doc/cmp.txt @@ -24,7 +24,7 @@ This is nvim-cmp's document. 1. This help file uses the type definition notation like `{lsp,cmp,vim}.*` - You can find it in `../lua/cmp/types/init.lua`. -2. Advanced configuration is described on the wiki. +2. Advanced configuration is described in the wiki. - https://github.com/hrsh7th/nvim-cmp/wiki ============================================================================== @@ -32,17 +32,17 @@ Concept *cmp-concept* - Full support for LSP completion related capabilities - Powerful customization abilities via Lua functions -- Smart handling of key mapping +- Smart handling of key mappings - No flicker ============================================================================== Usage *cmp-usage* -Recommended configuration is written below. +A recommended configuration can be found below. NOTE: - 1. You must provide `snippet.expand` function. - 2. `cmp.setup.cmdline` won't work if you use `native` completion menu. - 3. You can disable the `default` options via specifying `cmp.config.disable` value. + 1. You must provide a `snippet.expand` function. + 2. `cmp.setup.cmdline` won't work if you use the `native` completion menu. + 3. You can disable the `default` options by specifying `cmp.config.disable` value. > call plug#begin(s:plug_dir) Plug 'neovim/nvim-lspconfig' @@ -134,7 +134,7 @@ Recommended configuration is written below. ============================================================================== Function *cmp-function* -NOTE: `lua require('cmp').complete()` can be used to call these functions in mapping. +NOTE: `lua require('cmp').complete()` can be used to call these functions in a mapping. *cmp.setup* (config: cmp.ConfigSchema) Setup global configuration. See configuration options. @@ -146,41 +146,41 @@ NOTE: `lua require('cmp').complete()` can be used to call these functio Setup configuration for the current buffer. *cmp.setup.cmdline* (cmdtype: string, config: cmp.ConfigSchema) - Setup cmdline configuration for the specific type of cmd. - See |getcmdtype()| - NOTE: nvim-cmp does not support the `=` cmd type. + Setup cmdline configuration for the specific type of command. + See |getcmdtype()|. + NOTE: nvim-cmp does not support the `=` command type. *cmp.visible* () - Return boolean showing whether the completion menu is visible or not. + Return a boolean showing whether the completion menu is visible or not. *cmp.get_entries* () Return all current entries. *cmp.get_selected_entry* () - Return current selected entry (contains preselected). + Return currently selected entry (including preselected). *cmp.get_active_entry* () - Return current selected entry (without preselected). + Return currently selected entry (excluding preselected). *cmp.close* () Close the completion menu. *cmp.abort* () - Closes the completion menu and restore the current line to the state when it was started current completion. + Closes the completion menu and restore the current line to the state before the current completion was started. *cmp.select_next_item* (option: { behavior = cmp.SelectBehavior }) - Select next item. + Select the next item. *cmp.select_prev_item* (option: { behavior = cmp.SelectBehavior })* - Select previous item. + Select the previous item. *cmp.scroll_docs* (delta: number) - Scroll docs if visible. + Scroll the documentation window if visible. *cmp.complete* (option: { reason = cmp.ContextReason, config = cmp.ConfigSchema }) Invoke completion. - The following configurations defines the key mapping to show completion only for vsnip snippets. + The following configuration defines a key mapping to show completion only for vsnip snippets. > cmp.setup { mapping = { @@ -199,7 +199,7 @@ NOTE: `lua require('cmp').complete()` can be used to call these functio NOTE: `config` in that case means a temporary setting, but `config.mapping` remains permanent. *cmp.complete_common_string* () - Complete common string (reminds shell completion behavior). + Complete common string (similar to shell completion behavior). > cmp.setup { mapping = { @@ -213,11 +213,11 @@ NOTE: `lua require('cmp').complete()` can be used to call these functio } < *cmp.confirm* (option: cmp.ConfirmOption, callback: function) - Accepts current selected completion item. - If you didn't select any item and `{ select = true }` is specified for - this, nvim-cmp would automatically select the first item. + Accepts the currently selected completion item. + If you didn't select any item and the option table contains `select = true`, + nvim-cmp will automatically select the first item. -*cmp.event:on* ('%EVENT_NAME%, callback) +*cmp.event:on* (%EVENT_NAME%, callback) Subscribe to nvim-cmp's event. Events are listed below. - `complete_done`: emit after current completion is done. @@ -228,12 +228,12 @@ Mapping *cmp-mapping* Nvim-cmp's mapping mechanism is complex but flexible and user-friendly. -You can specify the mapping function that receives the `fallback` function as argument. +You can specify a mapping function that receives a `fallback` function as an argument. The `fallback` function can be used to call an existing mapping. -For example, typical pair-wise plugin automatically defines the mappings for `` and `(`. -Nvim-cmp might overwrite it via specified mapping. -But you can use existing mapping via invoking the `fallback` function. +For example, typical pair-wise plugins automatically define mappings for `` and `(`. +Nvim-cmp will overwrite it if you provide a mapping. To call the existing mapping, +you would need to invoke the `fallback` function. > cmp.setup { mapping = { @@ -241,7 +241,7 @@ But you can use existing mapping via invoking the `fallback` function. if cmp.visible() then cmp.confirm() else - fallback() -- If you use vim-endwise, this fallback will behave as vim-endwise. + fallback() -- If you use vim-endwise, this fallback will behave the same as vim-endwise. end end } @@ -260,7 +260,7 @@ But you can use existing mapping via invoking the `fallback` function. } < -And you can specify the mapping modes. +It is possible to specify the modes the mapping should be active in (`i` = insert mode, `c` = command mode, `s` = select mode): > cmp.setup { mapping = { @@ -268,7 +268,7 @@ And you can specify the mapping modes. } } < -And you can specify different mappings for different modes using the same key. +You can also specify different mappings for different modes by passing a table: > cmp.setup { mapping = { @@ -279,7 +279,7 @@ And you can specify different mappings for different modes using the same key. } } < -You can also use built-in mapping helpers. +There are also builtin mapping helper functions you can use: *cmp.mapping.close* () Same as |cmp.close|. @@ -313,33 +313,33 @@ Command *cmp-command* *CmpStatus* Describes statuses and states of sources. - Sometimes `unknown` source will be printed but it isn't problem. - For that reason `cmp-nvim-lsp` registered on the InsertEnter autocmd will - have `unknown` status. + Sometimes `unknown` will be printed - this is expected. + For example, `cmp-nvim-lsp` registers itself on InsertEnter autocommand + so the status will be shown as `unknown` when running the command. ============================================================================== Highlight *cmp-highlight* *CmpItemAbbr* - Highlights unmatched characters of each completion field. + Highlight group for unmatched characters of each completion field. *CmpItemAbbrDeprecated* - Highlights unmatched characters of each deprecated completion field. + Highlight group for unmatched characters of each deprecated completion field. *CmpItemAbbrMatch* - Highlights matched characters of each completion field. Matched characters + Highlight group for matched characters of each completion field. Matched characters must form a substring of a field which share a starting position. *CmpItemAbbrMatchFuzzy* - Highlights fuzzy-matched characters of each completion field. + Highlight group for fuzzy-matched characters of each completion field. *CmpItemKind* - Highlights kind of the field. + Highlight group for the kind of the field. NOTE: `kind` is a symbol after each completion option. *CmpItemKind%KIND_NAME%* - Highlights kind of the field for specific `lsp.CompletionItemKind`. + Highlight group for the kind of the field for a specific `lsp.CompletionItemKind`. If you only want to overwrite the `method` kind's highlight group, you can do this: > highlight CmpItemKindMethod guibg=NONE guifg=Orange @@ -371,9 +371,9 @@ preselect~ `cmp.PreselectMode` 1. `cmp.PreselectMode.Item` - nvim-cmp will pre-select the item that the source specified. + nvim-cmp will preselect the item that the source specified. 2. `cmp.PreselectMode.None` - nvim-cmp wouldn't pre-select any items. + nvim-cmp will not preselect any items. *cmp-config.mapping* mapping~ @@ -383,7 +383,8 @@ mapping~ *cmp-config.snippet.expand* snippet.expand~ `fun(option: cmp.SnippetExpansionParams)` - The snippet expansion function. That's how cmp interacts with snippet engine. + The snippet expansion function. That's how nvim-cmp interacts with a + particular snippet engine. *cmp-config.completion.keyword_length* completion.keyword_length~ @@ -398,33 +399,33 @@ completion.keyword_pattern~ *cmp-config.completion.autocomplete* completion.autocomplete~ `cmp.TriggerEvent[] | false` - The event to trigger autocompletion. If false specified, than completion is - only invoked manually. + The event to trigger autocompletion. If set to `false`, then completion is + only invoked manually (e.g. by calling `cmp.complete`). *cmp-config.completion.completeopt* completion.completeopt~ `string` - The vim's completeopt-like setting. See 'completeopt'. - Besically, you don't need to change this. + Like vim's completeopt setting. See 'completeopt'. + In general, you don't need to change this. *cmp-config.confirmation.get_commit_characters* confirmation.get_commit_characters~ `fun(commit_characters:string[]):string[]` - You can append or exclude commitCharacters via this configuration option function. - The commitCharacters is defined by LSP spec. + You can append or exclude commitCharacters via this configuration option + function. The commitCharacters are defined by the LSP spec. *cmp-config.formatting.fields* formatting.fields~ `cmp.ItemField[]` - The array of completion fields to specify their order. + An array of completion fields to specify their order. *cmp-config.formatting.format* formatting.format~ `fun(entry: cmp.Entry, vim_item: vim.CompletedItem): vim.CompletedItem` - The function used to customize the completion menu appearance. See - |complete-items|. This value can also be used to modify `dup` property. - NOTE: The `vim.CompletedItem` can have special properties `abbr_hl_group`, - `kind_hl_group` and `menu_hl_group`. + The function used to customize the appearance of the completion menu. See + |complete-items|. This value can also be used to modify the `dup` property. + NOTE: The `vim.CompletedItem` can contain the special properties + `abbr_hl_group`, `kind_hl_group` and `menu_hl_group`. *cmp-config.matching.disallow_fuzzy_matching* matching.disallow_fuzzy_matching~ @@ -460,50 +461,50 @@ sorting.comparators~ sources~ `cmp.SourceConfig[]` List of the sources and their configurations to use. - Order of the sources matters for sorting order. + The order of the sources determines their order in the completion results. *cmp-config.sources[n].name* sources[n].name~ `string` - The source name. + The name of the source. *cmp-config.sources[n].option* sources[n].option~ `table` - The specific options defined by the source itself. + Any specific options defined by the source itself. *cmp-config.sources[n].keyword_length* sources[n].keyword_length~ `number` - The source specific keyword length to trigger auto completion. + The source-specific keyword length to trigger auto completion. *cmp-config.sources[n].keyword_pattern* sources[n].keyword_pattern~ `string` - The source specific keyword pattern. + The source-specific keyword pattern. *cmp-config.sources[n].trigger_characters* sources[n].trigger_characters~ `string[]` - The source specific keyword pattern. + A source-specific keyword pattern. *cmp-config.sources[n].priority* sources[n].priority~ `number` - The source specific priority value. + The source-specific priority value. *cmp-config.sources[n].max_item_count* sources[n].max_item_count~ `number` - The source specific item count. + The source-specific item count. *cmp-config.sources[n].group_index* sources[n].group_index~ `number` The source group index. - For instance, you can specify the `buffer`'s source `group_index` to bigger number - if you don't want to see the buffer source items when nvim-lsp source is available. + For instance, you can set the `buffer`'s source `group_index` to a larger number + if you don't want to see `buffer` source items while `nvim-lsp` source is available: > cmp.setup { sources = { @@ -512,7 +513,7 @@ sources[n].group_index~ } } < - You can specify this via the built-in configuration helper like this. + You can also achieve this by using the built-in configuration helper like this: > cmp.setup { sources = cmp.config.sources({ @@ -525,7 +526,7 @@ sources[n].group_index~ *cmp-config.view* view~ `{ entries: cmp.EntriesConfig|string }` - Specify the view class to customize appearance. + The view class used to customize nvim-cmp's appearance. Currently available configuration options are: *cmp-config.window.{completion,documentation}.border* @@ -587,11 +588,11 @@ cmp.config.context~ *cmp.config.context.in_treesitter_capture* (capture) You can specify the treesitter capture name. - If you don't use `nvim-treesitter`, this helper doesn't work correctly. + If you don't use the `nvim-treesitter` plugin, this helper will not work correctly. cmp.config.mapping~ - See |cmp-mapping| + See |cmp-mapping|. cmp.config.sources~ @@ -611,7 +612,7 @@ cmp.config.sources~ cmp.config.window~ *cmp.config.window.bordered* (option) - Make window `bordered`. + Make the completion window `bordered`. The option is described in `cmp.ConfigSchema`. > cmp.setup { @@ -624,46 +625,46 @@ cmp.config.window~ ============================================================================== Develop *cmp-develop* -Create custom source~ +Creating a custom source~ NOTE: 1. The `complete` method is required. Others can be omitted. - 2. The `callback` argument must always be called. + 2. The `callback` function must always be called. 3. You can use only `require('cmp')` in custom source. - 4. If LSP spec was changed, nvim-cmp would follow it without any announcement. + 4. If the LSP spec was changed, nvim-cmp may implement it without any announcement (potentially introducing breaking changes). 5. You should read ./lua/cmp/types and https://microsoft.github.io/language-server-protocol/specifications/specification-current. - 6. Please add `nvim-cmp` topic for github repo. - -You can create custom source like the following example. + 6. Please add your source to the list of sources in the Wiki (https://github.com/hrsh7th/nvim-cmp/wiki/List-of-sources) + and if you publish it on GitHub, add the `nvim-cmp` topic so users can find it more easily. +Here is an example on how to create a custom source: > local source = {} - ---Return this source is available in current context or not. (Optional) + ---Return whether this source is available in the current context or not (optional). ---@return boolean function source:is_available() return true end - ---Return the debug name of this source. (Optional) + ---Return the debug name of this source (optional). ---@return string function source:get_debug_name() return 'debug name' end - ---Return keyword pattern for triggering completion. (Optional) - ---If this is ommited, nvim-cmp will use default keyword pattern. See |cmp-config.completion.keyword_pattern| + ---Return the keyword pattern for triggering completion (optional). + ---If this is ommited, nvim-cmp will use a default keyword pattern. See |cmp-config.completion.keyword_pattern|. ---@return string function source:get_keyword_pattern() return [[\k\+]] end - ---Return trigger characters for triggering completion. (Optional) + ---Return trigger characters for triggering completion (optional). function source:get_trigger_characters() return { '.' } end - ---Invoke completion. (Required) + ---Invoke completion (required). ---@param params cmp.SourceCompletionApiParams ---@param callback fun(response: lsp.CompletionResponse|nil) function source:complete(params, callback) @@ -683,21 +684,22 @@ You can create custom source like the following example. }) end - ---Resolve completion item. (Optional) + ---Resolve completion item (optional). This is called right before the completion is about to be displayed. + ---Useful for setting the text shown in the documentation window (`completion_item.documentation`). ---@param completion_item lsp.CompletionItem ---@param callback fun(completion_item: lsp.CompletionItem|nil) function source:resolve(completion_item, callback) callback(completion_item) end - ---Execute command after item was accepted. + ---Executed after the item was selected. ---@param completion_item lsp.CompletionItem ---@param callback fun(completion_item: lsp.CompletionItem|nil) function source:execute(completion_item, callback) callback(completion_item) end - ---Register custom source to nvim-cmp. + ---Register your source to nvim-cmp. require('cmp').register_source('month', source.new()) < ============================================================================== @@ -706,20 +708,19 @@ FAQ *cmp-faq* Why does cmp automatically select a particular item? ~ How to disable the preselect feature? ~ - Nvim-cmp respects LSP(Language Server Protocol) specification. + Nvim-cmp respects the LSP (Language Server Protocol) specification. The LSP spec defines the `preselect` feature for completion. - You can disable the `preselect` feature like the following. + You can disable the `preselect` feature like this: > cmp.setup { preselect = cmp.PreselectMode.None } < -Why nvim-cmp confirm item automatically?~ How to disable commitCharacters?~ - You can disable commitCharacters feature (that defined in LSP spec). + You can disable the commitCharacters feature (which is defined in LSP spec): > cmp.setup { confirmation = { @@ -732,9 +733,9 @@ How to disable commitCharacters?~ How to disable auto-completion?~ -How to use nvim-cmp as like omnifunc?~ +How to use nvim-cmp as omnifunc?~ - You can disable auto-completion like this. + You can disable auto-completion like this: > cmp.setup { ... @@ -744,15 +745,15 @@ How to use nvim-cmp as like omnifunc?~ ... } < - And you can invoke completion manually. + Then you will need to nvoke completion manually. > inoremap lua require('cmp').complete() < -How to disable nvim-cmp on the specific buffer?~ -How to setup on the specific buffer?~ +How to disable nvim-cmp for a specific buffer?~ +How to setup nvim-cmp for a specific buffer?~ - You can setup buffer specific configuration like this. + You can setup buffer-specific configuration like this: > cmp.setup.filetype({ 'markdown', 'help' }, { sources = { @@ -762,9 +763,9 @@ How to setup on the specific buffer?~ }) < -How to disable documentation window?~ +How to disable the documentation window?~ - You can use the following config. + Simply use the following config: > cmp.setup.filetype({ 'markdown', 'help' }, { window = { @@ -778,12 +779,12 @@ How to integrate with copilot.vim?~ Copilot.vim and nvim-cmp both have a `key-mapping fallback` mechanism. Therefore, you should manage those plugins by yourself. - Fortunately, the copilot.vim has the feature that disables the fallback mechanism. + Fortunately, the copilot.vim has a feature that disables the fallback mechanism. > let g:copilot_no_tab_map = v:true imap (vimrc:copilot-dummy-map) copilot#Accept("\") < - You can manage copilot.vim's accept feature with nvim-cmp' key-mapping configuration. + You can manage copilot.vim's accept feature inside nvim-cmp's key-mapping function: > cmp.setup { mapping = { @@ -798,9 +799,9 @@ How to integrate with copilot.vim?~ < -How to customize menu appearance?~ +How to customize the menu appearance?~ - You can see nvim-cmp wiki (https://github.com/hrsh7th/nvim-cmp/wiki). + Have a look at the wiki (https://github.com/hrsh7th/nvim-cmp/wiki). ============================================================================== vim:tw=78:ts=2:et:ft=help:norl: