docs(nvim): inline documentation.

Author: Davidyz

lua/vectorcode/cacher.lua

@@ -107,8 +107,14 @@ local function async_runner(query_message, buf_nr)
 end
 
 M.register_buffer = vc_config.check_cli_wrap(
-  ---@param bufnr integer?
-  ---@param opts VectorCode.RegisterOpts?
+  ---This function registers a buffer to be cached by VectorCode. The
+  ---registered buffer can be aquired by the `query_from_cache` API.
+  ---The retrieval of the files occurs in the background, so this
+  ---function will not block the main thread.
+  ---
+  ---NOTE: this function uses an autocommand to track the changes to the buffer and trigger retrieval.
+  ---@param bufnr integer? Default to the current buffer.
+  ---@param opts VectorCode.RegisterOpts? Async options.
   function(bufnr, opts)
     if bufnr == 0 or bufnr == nil then
       bufnr = vim.api.nvim_get_current_buf()
@@ -166,6 +172,10 @@ M.register_buffer = vc_config.check_cli_wrap(
 )
 
 M.deregister_buffer = vc_config.check_cli_wrap(
+  ---This function deregisters a buffer from VectorCode. This will kill all
+  ---running jobs, delete cached results, and deregister the autocommands
+  ---associated with the buffer. If the caching has not been registered, an
+  ---error notification will bef ired.
   ---@param bufnr integer?
   ---@param opts {notify:boolean}
   function(bufnr, opts)
@@ -204,6 +214,8 @@ M.buf_is_registered = function(bufnr)
 end
 
 M.query_from_cache = vc_config.check_cli_wrap(
+  ---This function queries VectorCode from cache. Returns an array of results. Each item
+  ---of the array is in the format of `{path="path/to/your/code.lua", document="document content"}`.
   ---@param bufnr integer?
   ---@param opts {notify: boolean}?
   ---@return VectorCode.Result[]
@@ -233,8 +245,11 @@ M.query_from_cache = vc_config.check_cli_wrap(
   end
 )
 
+---@alias ComponentCallback fun(result:VectorCode.Result):string
+
+---Compile the retrieval results into a string.
 ---@param bufnr integer
----@param component_cb (fun(result:VectorCode.Result):string)?
+---@param component_cb ComponentCallback? The component callback that formats a retrieval result.
 ---@return {content:string, count:integer}
 function M.make_prompt_component(bufnr, component_cb)
   if bufnr == 0 or bufnr == nil then
@@ -257,6 +272,8 @@ function M.make_prompt_component(bufnr, component_cb)
   return { content = final_component, count = #retrieval }
 end
 
+---Checks if VectorCode has been configured properly for your project.
+---See the CLI manual for details.
 ---@param check_item string?
 ---@param on_success fun(out: vim.SystemCompleted)?
 ---@param on_failure fun(out: vim.SystemCompleted?)?

lua/vectorcode/init.lua

@@ -6,10 +6,14 @@ local get_config = vc_config.get_user_config
 local notify_opts = vc_config.notify_opts
 
 M.query = vc_config.check_cli_wrap(
-  ---@param query_message string|string[]
-  ---@param opts VectorCode.QueryOpts?
-  ---@param callback fun(result:VectorCode.Result[])?
-  ---@return VectorCode.Result[]?
+  ---This function wraps the `query` subcommand of the VectorCode CLI. When used without the `callback` parameter,
+  ---this function works as a synchronous function and return the results. Otherwise, this function will run async
+  ---and the results are accessible by the `callback` function (the results will be passed as the argument to the
+  ---callback).
+  ---@param query_message string|string[] Query message(s) to send to the `vecctorcode query` command
+  ---@param opts VectorCode.QueryOpts? A table of config options. If nil, the default config or `setup` config will be used.
+  ---@param callback fun(result:VectorCode.Result[])? Use the result async style.
+  ---@return VectorCode.Result[]? An array of results.
   function(query_message, opts, callback)
     opts = vim.tbl_deep_extend("force", vc_config.get_query_opts(), opts or {})
     if opts.n_query == 0 then
@@ -83,8 +87,12 @@ M.query = vc_config.check_cli_wrap(
 )
 
 M.vectorise = vc_config.check_cli_wrap(
-  ---@param files string|string[]
-  ---@param project_root string?
+  ---This function wraps the `vectorise` subcommand. By default this function doesn't pass a `--project_root` flag.
+  ---The command will be run from the current working directory, and the normal project root detection logic in the
+  ---CLI will work as normal. You may also pass a `project_root` as the second argument, in which case the
+  ---`--project_root` will be passed.
+  ---@param files string|string[] Files to vectorise.
+  ---@param project_root string? Add the `--project_root` flag and the passed argument to the command.
   function(files, project_root)
     local args = { "--pipe", "vectorise" }
     if project_root ~= nil then
@@ -147,8 +155,8 @@ M.vectorise = vc_config.check_cli_wrap(
   end
 )
 
----@param check_item string?
----@param stdout_cb fun(stdout: vim.SystemCompleted)?
+---@param check_item string? See `vectorcode check` documentation.
+---@param stdout_cb fun(stdout: vim.SystemCompleted)? Gives user access to the exit code, stdout and signal.
 ---@return boolean
 function M.check(check_item, stdout_cb)
   if not vc_config.has_cli() then

lua/vectorcode/types.lua

@@ -1,26 +1,31 @@
+---Type definition of the retrieval result.
 ---@class VectorCode.Result
----@field path string
----@field document string
+---@field path string Path to the file
+---@field document string Content of the file
 
+---Type definitions for the cache of a buffer.
 ---@class VectorCode.Cache
----@field enabled boolean
----@field jobs table<integer, boolean>
----@field last_run integer?
----@field options VectorCode.RegisterOpts
----@field retrieval VectorCode.Result[]?
+---@field enabled boolean Whether the async jobs are enabled or not. If the buffer is disabled, no cache will be generated for it.
+---@field jobs table<integer, boolean> keeps track of running jobs.
+---@field last_run integer? Last time the query ran, in seconds from epoch.
+---@field options VectorCode.RegisterOpts The options that the buffer was registered with.
+---@field retrieval VectorCode.Result[]? The latest retrieval.
 
+---Type definitions for options accepted by `query` API.
 ---@class VectorCode.QueryOpts
----@field exclude_this boolean
----@field n_query integer
----@field notify boolean
----@field timeout_ms number
+---@field exclude_this boolean Whether to exclude the current buffer. Default: true
+---@field n_query integer Number of results.
+---@field notify boolean Notify on new results and other key moments.
+---@field timeout_ms number Timeout (in milliseconds) for running a vectorcode command. Default: 5000
 
+---Options passed to `setup`.
 ---@class VectorCode.Opts : VectorCode.QueryOpts
----@field async_opts VectorCode.RegisterOpts
+---@field async_opts VectorCode.RegisterOpts Default options to use for registering a new buffer for async cache.
 
+---Options for the registration of an async cache for a buffer.
 ---@class VectorCode.RegisterOpts: VectorCode.QueryOpts
----@field debounce integer
----@field events string|string[]
----@field single_job boolean
----@field query_cb VectorCode.QueryCallback
----@field run_on_register boolean
+---@field debounce integer Seconds. Default: 10
+---@field events string|string[] autocmd events that triggers async jobs. Default: `{"BufWritePost", "InsertEnter", "BufReadPost"}`
+---@field single_job boolean Whether to restrict to 1 async job per buffer. Default: false
+---@field query_cb VectorCode.QueryCallback Function that accepts the buffer ID and returns the query message(s). Default: `require("vectorcode.utils").make_surrounding_lines_cb(-1)`
+---@field run_on_register boolean Whether to run the query when registering. Default: false

lua/vectorcode/utils.lua

@@ -28,6 +28,9 @@ end
 
 ---@alias VectorCode.QueryCallback fun(bufnr:integer?):string|string[]
 
+---Retrieves all LSP document symbols from the current buffer, and use the symbols
+---as query messages. Fallbacks to `make_surrounding_lines_cb` if
+---`textDocument_documentSymbol` is not accessible.
 ---@return VectorCode.QueryCallback
 function M.make_lsp_document_symbol_cb()
   return function(bufnr)
@@ -63,7 +66,8 @@ function M.make_lsp_document_symbol_cb()
   end
 end
 
----@param num_of_lines integer
+---Use the lines above and below the current line as the query messages.
+---@param num_of_lines integer The number of lines to include in the query.
 ---@return VectorCode.QueryCallback
 function M.make_surrounding_lines_cb(num_of_lines)
   return function(bufnr)