docs(nvim): Fix type annotations and documentations for nvim plugin (#289)

* docs(nvim): fix type annotations

* refined docs

* Auto generate docs

Author: Davidyz

doc/VectorCode.txt

@@ -56,11 +56,10 @@ INSTALLATION                           *VectorCode-neovim-plugin-installation*
 Using Lazy:
 
 >lua
-    {
+    return {
       "Davidyz/VectorCode",
       version = "*", -- optional, depending on whether you're on nightly or release
       dependencies = { "nvim-lua/plenary.nvim" },
-      cmd = "VectorCode", -- if you're lazy-loading VectorCode
     }
 <
 
@@ -83,7 +82,7 @@ the neovim plugin updates. For example, if you’re using lazy.nvim and `uv`,
 you can use the following plugin spec:
 
 >lua
-    {
+    return {
       "Davidyz/VectorCode",
       version = "*",
       build = "uv tool upgrade vectorcode", -- This helps keeping the CLI up-to-date
@@ -121,11 +120,11 @@ sufficient to simply add VectorCode as a dependency. You’d also need to wrap
 the `opts` table in a function:
 
 >lua
-    {
+    return {
       "olimorris/codecompanion.nvim",
       opts = function()
         return your_opts_here
-      end
+      end,
     }
 <
 

docs/neovim/README.md

@@ -47,11 +47,10 @@
 Using Lazy:
 
 ```lua 
-{
+return {
   "Davidyz/VectorCode",
   version = "*", -- optional, depending on whether you're on nightly or release
   dependencies = { "nvim-lua/plenary.nvim" },
-  cmd = "VectorCode", -- if you're lazy-loading VectorCode
 }
 ```
 The VectorCode CLI and neovim plugin share the same release scheme (version
@@ -74,7 +73,7 @@ the neovim plugin updates. For example, if you're using lazy.nvim and `uv`,
 you can use the following plugin spec:
 
 ```lua
-{
+return {
   "Davidyz/VectorCode",
   version = "*",
   build = "uv tool upgrade vectorcode", -- This helps keeping the CLI up-to-date
@@ -106,11 +105,11 @@ For example, in [lazy.nvim](https://github.com/folke/lazy.nvim), it's not
 sufficient to simply add VectorCode as a dependency. You'd also need to wrap the 
 `opts` table in a function:
 ```lua
-{
+return {
   "olimorris/codecompanion.nvim",
   opts = function()
     return your_opts_here
-  end
+  end,
 }
 ```
 If you pass a table, instead of a function, as the value for the `opts` key,

lua/codecompanion/_extensions/vectorcode/init.lua

@@ -3,18 +3,18 @@
 ---@alias sub_cmd "ls"|"query"|"vectorise"|"files_ls"|"files_rm"
 
 ---@class VectorCode.CodeCompanion.ExtensionOpts
---- A table where the keys are the subcommand name (`ls`, `query`, `vectorise`)
+---A table where the keys are the subcommand name (`ls`, `query`, `vectorise`, etc.)
 --- and the values are their config options.
----@field tool_opts table<sub_cmd, VectorCode.CodeCompanion.ToolOpts>
---- Whether to add a tool group that contains all vectorcode tools.
----@field tool_group VectorCode.CodeCompanion.ToolGroupOpts
+---@field tool_opts? table<sub_cmd|"*", VectorCode.CodeCompanion.ToolOpts>
+---Options related to the `vectorcode_toolbox` tool group
+---@field tool_group? VectorCode.CodeCompanion.ToolGroupOpts
 ---Prompt library that automatically creates VectorCode collections on local files
 ---and set up prompts to let LLM search from certain directories.
 ---
 ---The keys should be the human-readable name of the prompt (as they'd appear in
 ---the action menu), and values would be `VectorCode.CodeCompanion.PromptFactory.Opts`
 ---objects.
----@field prompt_library table<string, VectorCode.CodeCompanion.PromptFactory.Opts>
+---@field prompt_library? table<string, VectorCode.CodeCompanion.PromptFactory.Opts>
 
 local vc_config = require("vectorcode.config")
 local logger = vc_config.logger
@@ -25,22 +25,20 @@ local default_extension_opts = {
   tool_opts = {
     -- NOTE: the other default opts are defined in the source code files of the tools.
     -- `include_in_toolbox` is here so that the extension setup works as expected.
-
     ls = { include_in_toolbox = true },
     query = { include_in_toolbox = true },
     vectorise = { include_in_toolbox = true },
     files_ls = {},
     files_rm = {},
   },
   tool_group = { enabled = true, collapse = true, extras = {} },
-
   prompt_library = require("vectorcode.integrations.codecompanion.prompts.presets"),
 }
 
 ---@type sub_cmd[]
 local valid_tools = { "ls", "query", "vectorise", "files_ls", "files_rm" }
 
----@param tool_opts table<sub_cmd, VectorCode.CodeCompanion.ToolOpts>
+---@param tool_opts table<sub_cmd|"*", VectorCode.CodeCompanion.ToolOpts>
 ---@return table<sub_cmd, VectorCode.CodeCompanion.ToolOpts>
 local function merge_tool_opts(tool_opts)
   local wildcard_opts = tool_opts["*"]
@@ -50,7 +48,9 @@ local function merge_tool_opts(tool_opts)
         tool_opts[tool_name] = vim.tbl_deep_extend("force", wildcard_opts, opts)
       end
     end
+    tool_opts["*"] = nil
   end
+  ---@cast tool_opts table<sub_cmd, VectorCode.CodeCompanion.ToolOpts>
   return tool_opts
 end
 
@@ -130,14 +130,15 @@ local M = {
           vc_config.notify_opts
         )
       end
-      if type(prompt_opts.project_root) == "function" then
-        prompt_opts.project_root = prompt_opts.project_root()
+      local project_root = prompt_opts.project_root
+      if type(project_root) == "function" then
+        project_root = project_root()
       end
-      if not utils.is_directory(prompt_opts.project_root) then
+      if not utils.is_directory(project_root) then
         vim.notify(
           string.format(
             "`%s` is not a valid directory for CodeCompanion prompt library.\nSkipping `%s`.",
-            prompt_opts.project_root,
+            project_root,
             name
           ),
           vim.log.levels.WARN,

lua/vectorcode/types.lua

@@ -53,12 +53,12 @@
 
 ---Options for the registration of an async cache for a buffer.
 ---@class VectorCode.RegisterOpts: VectorCode.QueryOpts
----@field debounce integer? Seconds. Default: 10
----@field events string|string[]|nil 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
----@field project_root string?
+---@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
+---@field project_root? string
 
 ---A unified interface used by `lsp` backend and `default` backend
 ---@class VectorCode.CacheBackend
@@ -96,29 +96,29 @@
 --- Users may ask the LLM to request a different number of results in the chat.
 --- You may set this to a table to configure different values for document/chunk mode.
 --- Default: `{ document = 10, chunk = 50 }`
----@field default_num integer|{document:integer, chunk: integer}|nil
+---@field default_num? integer|{document:integer, chunk: integer}
 --- Whether to avoid duplicated references. Default: `true`
 ---@field no_duplicate boolean?
 --- Whether to send chunks instead of full files to the LLM. Default: `false`
 --- > Make sure you adjust `max_num` and `default_num` accordingly.
----@field chunk_mode boolean?
----@field summarise VectorCode.CodeCompanion.SummariseOpts?
+---@field chunk_mode? boolean
+---@field summarise? VectorCode.CodeCompanion.SummariseOpts
 
 ---@class VectorCode.CodeCompanion.VectoriseToolOpts: VectorCode.CodeCompanion.ToolOpts
 
 ---@class VectorCode.CodeCompanion.ToolGroupOpts
---- Whether to register the tool group
----@field enabled boolean
---- Whether to show the individual tools in the references
----@field collapse boolean
---- Other tools that you'd like to include in `vectorcode_toolbox`
----@field extras string[]
+---Whether to register the tool group
+---@field enabled? boolean
+---Whether to show the individual tools in the references
+---@field collapse? boolean
+---Other tools that you'd like to include in `vectorcode_toolbox`
+---@field extras? string[]
 
 --- The result of the query tool should be structured in the following table
 ---@class VectorCode.CodeCompanion.QueryToolResult
 ---@field raw_results VectorCode.QueryResult[]
 ---@field count integer
----@field summary string|nil
+---@field summary? string
 
 ---@class VectorCode.CodeCompanion.SummariseOpts
 ---A boolean flag that controls whether summarisation should be enabled.
@@ -128,13 +128,13 @@
 ---This function recieves 2 parameters:
 --- - `CodeCompanion.Chat`: the chat object;
 --- - `VectorCode.QueryResult[]`: a list of query results.
----@field enabled boolean|(fun(chat: CodeCompanion.Chat, results: VectorCode.QueryResult[]):boolean)|nil
+---@field enabled? boolean|(fun(chat: CodeCompanion.Chat, results: VectorCode.QueryResult[]):boolean)
 ---The adapter used for the summarisation task. When set to `nil`, the adapter from the current chat will be used.
----@field adapter string|CodeCompanion.HTTPAdapter|fun():CodeCompanion.HTTPAdapter|nil
+---@field adapter? string|CodeCompanion.HTTPAdapter|fun():CodeCompanion.HTTPAdapter
 ---The system prompt sent to the summariser model.
 ---When set to a function, it'll recieve the default system prompt as the only parameter,
 ---and should return the new (full) system prompt. This allows you to customise or rewrite the system prompt.
----@field system_prompt string|(fun(original_prompt: string): string)
+---@field system_prompt? string|(fun(original_prompt: string): string)
 ---When set to true, include the query messages so that the LLM may make task-related summarisations.
 ---This happens __after__ the `system_prompt` callback processing
----@field query_augmented boolean
+---@field query_augmented? boolean