refactor: add docs & type annotations

Added code documentation and some explanations.

Author: luckasRanarison

lua/nvim-devdocs/build.lua

@@ -1,6 +1,9 @@
 local notify = require("nvim-devdocs.notify")
 local transpiler = require("nvim-devdocs.transpiler")
 
+---@param entry RegisteryEntry
+---@param index any
+---@param docs table<string, string>
 local function build_docs(entry, index, docs)
   local alias = entry.slug:gsub("~", "-")
   local current_doc_dir = DOCS_DIR:joinpath(alias)

lua/nvim-devdocs/completion.lua

@@ -2,6 +2,8 @@ local M = {}
 
 local list = require("nvim-devdocs.list")
 
+---@param arg_lead string
+---@return string[]
 M.get_non_installed = function(arg_lead)
   if not REGISTERY_PATH:exists() then return {} end
 
@@ -19,6 +21,8 @@ M.get_non_installed = function(arg_lead)
   return args
 end
 
+---@param arg_lead string
+---@return string[]
 M.get_installed = function(arg_lead)
   local installed = list.get_installed_alias()
   local args = vim.tbl_filter(function(entry)
@@ -30,6 +34,8 @@ M.get_installed = function(arg_lead)
   return args
 end
 
+---@param arg_lead string
+---@return string[]
 M.get_updatable = function(arg_lead)
   local updatable = list.get_updatable()
   local args = vim.tbl_filter(function(entry)

lua/nvim-devdocs/config.lua

@@ -2,7 +2,8 @@ local M = {}
 
 local path = require("plenary.path")
 
-local config = {
+---@class nvim_devdocs.Config
+local default = {
   dir_path = vim.fn.stdpath("data") .. "/devdocs",
   telescope = {},
   float_win = {
@@ -25,27 +26,26 @@ local config = {
   after_open = function(bufnr) end,
 }
 
-M.get = function() return config end
+---@class nvim_devdocs.Config
+M.options = {}
 
 M.setup = function(new_config)
-  if new_config ~= nil then
-    for key, value in pairs(new_config) do
-      config[key] = value
-    end
-  end
+  M.options = vim.tbl_deep_extend("force", default, new_config or {})
 
-  DATA_DIR = path:new(config.dir_path)
+  DATA_DIR = path:new(default.dir_path)
   DOCS_DIR = DATA_DIR:joinpath("docs")
   INDEX_PATH = DATA_DIR:joinpath("index.json")
   LOCK_PATH = DATA_DIR:joinpath("docs-lock.json")
   REGISTERY_PATH = DATA_DIR:joinpath("registery.json")
 
-  return config
+  return default
 end
 
+---@param bufnr number
+---@param entry DocEntry
 M.set_keymaps = function(bufnr, entry)
   local slug = entry.alias:gsub("-", "~")
-  local keymaps = config.mappings
+  local keymaps = M.options.mappings
   local set_buf_keymap = function(key, action, description)
     vim.keymap.set("n", key, action, { buffer = bufnr, desc = description })
   end

lua/nvim-devdocs/init.lua

@@ -75,7 +75,7 @@ end
 M.setup = function(opts)
   config.setup(opts)
 
-  local ensure_installed = config.get().ensure_installed
+  local ensure_installed = config.options.ensure_installed
 
   vim.defer_fn(function() operations.install_args(ensure_installed) end, 3000)
 

lua/nvim-devdocs/list.lua

@@ -2,6 +2,7 @@ local M = {}
 
 local notify = require("nvim-devdocs.notify")
 
+---@return string[]
 M.get_installed_alias = function()
   if not LOCK_PATH:exists() then return {} end
 
@@ -12,6 +13,7 @@ M.get_installed_alias = function()
   return installed
 end
 
+---@return RegisteryEntry[] | nil
 M.get_installed_entry = function()
   if not REGISTERY_PATH:exists() then
     notify.log_err("Devdocs registery not found, please run :DevdocsFetch")
@@ -32,6 +34,7 @@ M.get_installed_entry = function()
   return results
 end
 
+---@return string[]
 M.get_updatable = function()
   if not REGISTERY_PATH:exists() or not LOCK_PATH:exists() then return {} end
 

lua/nvim-devdocs/operations.lua

@@ -12,8 +12,6 @@ local build_docs = require("nvim-devdocs.build")
 local devdocs_site_url = "https://devdocs.io"
 local devdocs_cdn_url = "https://documents.devdocs.io"
 
-local plugin_config = config.get()
-
 M.fetch = function()
   notify.log("Fetching DevDocs registery...")
 
@@ -32,6 +30,9 @@ M.fetch = function()
   })
 end
 
+---@param entry RegisteryEntry
+---@param verbose? boolean
+---@param is_update? boolean
 M.install = function(entry, verbose, is_update)
   if not REGISTERY_PATH:exists() then
     if verbose then notify.log_err("DevDocs registery not found, please run :DevdocsFetch") end
@@ -89,6 +90,9 @@ M.install = function(entry, verbose, is_update)
   end
 end
 
+---@param args string[]
+---@param verbose? boolean
+---@param is_update? boolean
 M.install_args = function(args, verbose, is_update)
   if not REGISTERY_PATH:exists() then
     if verbose then notify.log_err("DevDocs registery not found, please run :DevdocsFetch") end
@@ -122,6 +126,7 @@ M.install_args = function(args, verbose, is_update)
   end
 end
 
+---@param alias string
 M.uninstall = function(alias)
   local installed = list.get_installed_alias()
 
@@ -143,6 +148,8 @@ M.uninstall = function(alias)
   end
 end
 
+---@param alias string
+---@return DocEntry[] | nil
 M.get_entries = function(alias)
   local installed = list.get_installed_alias()
   local is_installed = vim.tbl_contains(installed, alias)
@@ -159,6 +166,7 @@ M.get_entries = function(alias)
   return entries
 end
 
+---@return DocEntry[]
 M.get_all_entries = function()
   if not INDEX_PATH:exists() then return {} end
 
@@ -180,6 +188,8 @@ M.get_all_entries = function()
   return entries
 end
 
+---@param entry DocEntry
+---@param callback function
 M.read_entry = function(entry, callback)
   local splited_path = vim.split(entry.path, ",")
   local file = splited_path[1]
@@ -194,7 +204,10 @@ M.read_entry = function(entry, callback)
   end))
 end
 
--- if we have a pattern to search for, only consider lines after the pattern
+---if we have a pattern to search for, only consider lines after the pattern
+---@param lines string[]
+---@param pattern? string
+---@return string[]
 M.filter_doc = function(lines, pattern)
   if not pattern then return lines end
 
@@ -224,14 +237,16 @@ M.filter_doc = function(lines, pattern)
   return filtered_lines
 end
 
+---@param bufnr number
+---@param is_picker? boolean
 M.render_cmd = function(bufnr, is_picker)
-  vim.bo[bufnr].ft = plugin_config.previewer_cmd
+  vim.bo[bufnr].ft = config.options.previewer_cmd
 
   local lines = vim.api.nvim_buf_get_lines(bufnr, 0, -1, false)
   local chan = vim.api.nvim_open_term(bufnr, {})
-  local args = is_picker and plugin_config.picker_cmd_args or plugin_config.cmd_args
+  local args = is_picker and config.options.picker_cmd_args or config.options.cmd_args
   local previewer = job:new({
-    command = plugin_config.previewer_cmd,
+    command = config.options.previewer_cmd,
     args = args,
     on_stdout = vim.schedule_wrap(function(_, data)
       if not data then return end
@@ -246,19 +261,22 @@ M.render_cmd = function(bufnr, is_picker)
   previewer:start()
 end
 
+---@param entry DocEntry
+---@param bufnr number
+---@param float boolean
 M.open = function(entry, bufnr, float)
   vim.api.nvim_buf_set_option(bufnr, "modifiable", false)
 
   if not float then
     vim.api.nvim_set_current_buf(bufnr)
   else
     local ui = vim.api.nvim_list_uis()[1]
-    local row = (ui.height - plugin_config.float_win.height) * 0.5
-    local col = (ui.width - plugin_config.float_win.width) * 0.5
-    local float_opts = plugin_config.float_win
+    local row = (ui.height - config.options.float_win.height) * 0.5
+    local col = (ui.width - config.options.float_win.width) * 0.5
+    local float_opts = config.options.float_win
 
-    float_opts.row = plugin_config.row or row
-    float_opts.col = plugin_config.col or col
+    float_opts.row = config.options.float_win.row or row
+    float_opts.col = config.options.float_win.col or col
     float_opts.zindex = 10
 
     local win = nil
@@ -272,15 +290,15 @@ M.open = function(entry, bufnr, float)
       state.set("last_win", win)
     end
 
-    vim.wo[win].wrap = plugin_config.wrap
-    vim.wo[win].linebreak = plugin_config.wrap
+    vim.wo[win].wrap = config.options.wrap
+    vim.wo[win].linebreak = config.options.wrap
     vim.wo[win].nu = false
     vim.wo[win].relativenumber = false
   end
 
-  local ignore = vim.tbl_contains(plugin_config.cmd_ignore, entry.alias)
+  local ignore = vim.tbl_contains(config.options.cmd_ignore, entry.alias)
 
-  if plugin_config.previewer_cmd and not ignore then
+  if config.options.previewer_cmd and not ignore then
     M.render_cmd(bufnr)
   else
     vim.bo[bufnr].ft = "markdown"
@@ -289,9 +307,10 @@ M.open = function(entry, bufnr, float)
   vim.bo[bufnr].keywordprg = ":DevdocsKeywordprg"
 
   config.set_keymaps(bufnr, entry)
-  plugin_config.after_open(bufnr)
+  config.options.after_open(bufnr)
 end
 
+---@param keyword string
 M.keywordprg = function(keyword)
   local alias = state.get("current_doc")
   local float = state.get("last_mode") == "float"

lua/nvim-devdocs/pickers.lua

@@ -13,10 +13,10 @@ local notify = require("nvim-devdocs.notify")
 local operations = require("nvim-devdocs.operations")
 local transpiler = require("nvim-devdocs.transpiler")
 local plugin_state = require("nvim-devdocs.state")
-local plugin_config = require("nvim-devdocs.config").get()
+local plugin_config = require("nvim-devdocs.config")
 
-local new_docs_picker = function(prompt, entries, previwer, attach)
-  return pickers.new(plugin_config.telescope, {
+local new_docs_picker = function(prompt, entries, previewer, attach)
+  return pickers.new(plugin_config.options.telescope, {
     prompt_title = prompt,
     finder = finders.new_table({
       results = entries,
@@ -28,8 +28,8 @@ local new_docs_picker = function(prompt, entries, previwer, attach)
         }
       end,
     }),
-    sorter = config.generic_sorter(plugin_config.telescope),
-    previewer = previwer,
+    sorter = config.generic_sorter(plugin_config.options.telescope),
+    previewer = previewer,
     attach_mappings = attach,
   })
 end
@@ -55,7 +55,7 @@ local doc_previewer = previewers.new_buffer_previewer({
     operations.read_entry(entry.value, function(filtered_lines)
       vim.api.nvim_buf_set_lines(bufnr, 0, -1, false, filtered_lines)
 
-      if plugin_config.previewer_cmd and plugin_config.picker_cmd then
+      if plugin_config.options.previewer_cmd and plugin_config.options.picker_cmd then
         plugin_state.set("preview_lines", filtered_lines)
         operations.render_cmd(bufnr, true)
       else
@@ -68,7 +68,7 @@ local doc_previewer = previewers.new_buffer_previewer({
 local open_doc = function(selection, float)
   local bufnr = nil
 
-  if plugin_config.picker_cmd then
+  if plugin_config.options.picker_cmd then
     bufnr = vim.api.nvim_create_buf(false, true)
     local lines = plugin_state.get("preview_lines")
     vim.api.nvim_buf_set_lines(bufnr, 0, -1, false, lines)
@@ -138,8 +138,10 @@ M.update_picker = function()
   picker:find()
 end
 
+---@param entries DocEntry[]
+---@param float? boolean
 M.open_picker = function(entries, float)
-  local picker = pickers.new(plugin_config.telescope, {
+  local picker = pickers.new(plugin_config.options.telescope, {
     prompt_title = "Select an entry",
     finder = finders.new_table({
       results = entries,
@@ -151,7 +153,7 @@ M.open_picker = function(entries, float)
         }
       end,
     }),
-    sorter = config.generic_sorter(plugin_config.telescope),
+    sorter = config.generic_sorter(plugin_config.options.telescope),
     previewer = doc_previewer,
     attach_mappings = function()
       actions.select_default:replace(function(prompt_bufnr)
@@ -172,6 +174,8 @@ M.open_picker = function(entries, float)
   picker:find()
 end
 
+---@param alias string
+---@param float? boolean
 M.open_picker_alias = function(alias, float)
   local entries = operations.get_entries(alias)