docs: add for public api

lua/blink/cmp/config/keymap.lua

@@ -4,7 +4,7 @@
 --- | 'hide' Hide the completion window
 --- | 'cancel' Cancel the current completion, undoing the preview from auto_insert
 --- | 'accept' Accept the current completion item
---- | 'select_and_accept' Select the current completion item and accept it
+--- | 'select_and_accept' Select the first completion item, if there's no selection, and accept
 --- | 'select_prev' Select the previous completion item
 --- | 'select_next' Select the next completion item
 --- | 'show_documentation' Show the documentation window
@@ -13,7 +13,7 @@
 --- | 'scroll_documentation_down' Scroll the documentation window down
 --- | 'snippet_forward' Move the cursor forward to the next snippet placeholder
 --- | 'snippet_backward' Move the cursor backward to the previous snippet placeholder
---- | (fun(cmp: blink.cmp.PublicAPI): boolean?) Custom function where returning true will prevent the next command from running
+--- | (fun(cmp: blink.cmp.API): boolean?) Custom function where returning true will prevent the next command from running
 
 --- @alias blink.cmp.KeymapPreset
 --- | 'none' No keymaps
@@ -108,7 +108,7 @@
 --- When defining your own keymaps without a preset, no keybinds will be assigned automatically.
 --- @class (exact) blink.cmp.BaseKeymapConfig
 --- @field preset? blink.cmp.KeymapPreset
---- @field [string] blink.cmp.KeymapCommand[]> Table of keys => commands[]
+--- @field [string] blink.cmp.KeymapCommand[] Table of keys => commands[]
 
 --- @class (exact) blink.cmp.KeymapConfig : blink.cmp.BaseKeymapConfig
 --- @field cmdline? blink.cmp.BaseKeymapConfig Optionally, define a separate keymap for cmdline

lua/blink/cmp/init.lua

@@ -1,7 +1,9 @@
-local has_setup = false
----@class blink.cmp.PublicAPI
+--- @class blink.cmp.API
 local cmp = {}
 
+local has_setup = false
+--- Initializes blink.cmp with the given configuration and initiates the download
+--- for the fuzzy matcher's prebuilt binaries, if necessary
 --- @param opts? blink.cmp.Config
 function cmp.setup(opts)
   if has_setup then return end
@@ -11,7 +13,7 @@ function cmp.setup(opts)
 
   local version = vim.version()
   if version.major == 0 and version.minor < 10 then
-    vim.notify('blink.cmp only supports nvim 0.10 and newer', vim.log.levels.ERROR, { title = 'blink.cmp' })
+    vim.notify('blink.cmp requires nvim 0.10 and newer', vim.log.levels.ERROR, { title = 'blink.cmp' })
     return
   end
 
@@ -38,6 +40,7 @@ function cmp.is_visible()
     or require('blink.cmp.completion.windows.ghost_text').is_open()
 end
 
+--- Show the completion window
 --- @params opts? { providers?: string[], callback?: fun() }
 function cmp.show(opts)
   opts = opts or {}
@@ -72,6 +75,7 @@ function cmp.show(opts)
   return true
 end
 
+--- Hide the completion window
 --- @params opts? { callback?: fun() }
 function cmp.hide(opts)
   if not cmp.is_visible() then return end
@@ -83,6 +87,7 @@ function cmp.hide(opts)
   return true
 end
 
+--- Cancel the current completion, undoing the preview from auto_insert
 --- @params opts? { callback?: fun() }
 function cmp.cancel(opts)
   if not cmp.is_visible() then return end
@@ -94,6 +99,7 @@ function cmp.cancel(opts)
   return true
 end
 
+--- Accept the current completion item
 --- @param opts? blink.cmp.CompletionListAcceptOpts
 function cmp.accept(opts)
   opts = opts or {}
@@ -107,6 +113,7 @@ function cmp.accept(opts)
   return true
 end
 
+--- Select the first completion item, if there's no selection, and accept
 --- @param opts? blink.cmp.CompletionListSelectAndAcceptOpts
 function cmp.select_and_accept(opts)
   if not cmp.is_visible() then return end
@@ -123,18 +130,21 @@ function cmp.select_and_accept(opts)
   return true
 end
 
+--- Select the previous completion item
 function cmp.select_prev()
   if not cmp.is_visible() then return end
   vim.schedule(function() require('blink.cmp.completion.list').select_prev() end)
   return true
 end
 
+--- Select the next completion item
 function cmp.select_next()
   if not cmp.is_visible() then return end
   vim.schedule(function() require('blink.cmp.completion.list').select_next() end)
   return true
 end
 
+--- Show the documentation window
 function cmp.show_documentation()
   local menu = require('blink.cmp.completion.windows.menu')
   local documentation = require('blink.cmp.completion.windows.documentation')
@@ -148,6 +158,7 @@ function cmp.show_documentation()
   return true
 end
 
+--- Hide the documentation window
 function cmp.hide_documentation()
   local documentation = require('blink.cmp.completion.windows.documentation')
   if not documentation.win:is_open() then return end
@@ -156,6 +167,7 @@ function cmp.hide_documentation()
   return true
 end
 
+--- Scroll the documentation window up
 --- @param count? number
 function cmp.scroll_documentation_up(count)
   local documentation = require('blink.cmp.completion.windows.documentation')
@@ -165,6 +177,7 @@ function cmp.scroll_documentation_up(count)
   return true
 end
 
+--- Scroll the documentation window down
 --- @param count? number
 function cmp.scroll_documentation_down(count)
   local documentation = require('blink.cmp.completion.windows.documentation')
@@ -174,16 +187,19 @@ function cmp.scroll_documentation_down(count)
   return true
 end
 
+--- Check if a snippet is active, optionally filtering by direction
 --- @param filter? { direction?: number }
 function cmp.snippet_active(filter) return require('blink.cmp.config').snippets.active(filter) end
 
+--- Move the cursor forward to the next snippet placeholder
 function cmp.snippet_forward()
   local snippets = require('blink.cmp.config').snippets
   if not snippets.active({ direction = 1 }) then return end
   vim.schedule(function() snippets.jump(1) end)
   return true
 end
 
+--- Move the cursor backward to the previous snippet placeholder
 function cmp.snippet_backward()
   local snippets = require('blink.cmp.config').snippets
   if not snippets.active({ direction = -1 }) then return end
@@ -195,12 +211,14 @@ end
 --- @param provider? string
 function cmp.reload(provider) require('blink.cmp.sources.lib').reload(provider) end
 
---- @param override? lsp.ClientCapabilities
---- @param include_nvim_defaults? boolean
+--- Gets the capabilities to pass to the LSP client
+--- @param override? lsp.ClientCapabilities Overrides blink.cmp's default capabilities
+--- @param include_nvim_defaults? boolean Whether to include nvim's default capabilities
 function cmp.get_lsp_capabilities(override, include_nvim_defaults)
   return require('blink.cmp.sources.lib').get_lsp_capabilities(override, include_nvim_defaults)
 end
 
+--- Add a new source provider at runtime
 --- @param id string
 --- @param provider_config blink.cmp.SourceProviderConfig
 function cmp.add_provider(id, provider_config)