Fix docstrings and formatting, and follow lsp suggestions

lua/devcontainer_cli/devcontainer_cli.lua

@@ -20,15 +20,13 @@ local function define_autocommands()
 end
 
 -- executes a given command in the devcontainer of the current project directory
----@param opts options for executing the command
+---@param opts (table) options for executing the command
 function M.exec(opts)
-  cwd = vim.loop.cwd()
-
   vim.validate({ args = { opts.args, "string" } })
   if opts.args == nil or opts.args == "" then
-    devcontainer_utils.exec(cwd)
+    devcontainer_utils.exec()
   else
-    devcontainer_utils.exec_cmd(opts.args, cwd)
+    devcontainer_utils.exec_cmd(opts.args)
   end
 end
 

lua/devcontainer_cli/devcontainer_utils.lua

@@ -17,26 +17,24 @@ local on_detach = function()
 end
 
 -- on_fail callback
----@param exit_code the exit code from the failed job
+---@param exit_code (integer) the exit code from the failed job
 local on_fail = function(exit_code)
   vim.notify(
-      "Devcontainer process has failed! exit_code: " .. exit_code,
-      vim.log.levels.ERROR
+    "Devcontainer process has failed! exit_code: " .. exit_code,
+    vim.log.levels.ERROR
   )
 
   vim.cmd("silent! :checktime")
 end
 
 local on_success = function()
-    vim.notify("Devcontainer process succeeded!", vim.log.levels.INFO)
+  vim.notify("Devcontainer process succeeded!", vim.log.levels.INFO)
 end
 
--- on_exit callback function to delete the open buffer when devcontainer exits 
+-- on_exit callback function to delete the open buffer when devcontainer exits
 -- in a neovim terminal
----@param job_id the id of the running job
----@param code the exit code
----@param event thrown by job
-local on_exit = function(job_id, code, event)
+---@param code (integer) the exit code
+local on_exit = function(_, code, _)
   if code == 0 then
     on_success()
     return
@@ -46,42 +44,40 @@ local on_exit = function(job_id, code, event)
 end
 
 --- execute command
----@param cmd the command to execute in the devcontainer terminal
+---@param cmd (string) the command to execute in the devcontainer terminal
 local function exec_command(cmd)
   vim.fn.termopen(
-    cmd, 
-    { 
+    cmd,
+    {
       on_exit = on_exit,
-      on_stdout = function(_, data, _)
-        vim .api.nvim_win_call(
+      on_stdout = function(_, _, _)
+        vim.api.nvim_win_call(
           win,
           function()
             vim.cmd("normal! G")
           end
-        ) 
+        )
       end,
     }
   )
   vim.api.nvim_set_current_buf(buffer)
 end
 
 -- create a new window and execute the given command
----@param cmd the command to execute in the devcontainer terminal
-function spawn_and_execute(cmd)
+---@param cmd (string) the command to execute in the devcontainer terminal
+local function spawn_and_execute(cmd)
   prev_win = vim.api.nvim_get_current_win()
-  win, buffer = windows_utils.open_floating_window()
+  win, buffer = windows_utils.open_floating_window(on_detach)
   exec_command(cmd)
 end
 
 -- build the initial part of a devcontainer command
----@param action the action for the devcontainer to perform 
--- (see man devcontainer) 
----@param cwd the current working directory. Used as a starting place to find 
--- .devcontainer directory
----@return nil if no devcontainer_parent could be found otherwise 
+---@param action (string) the action for the devcontainer to perform
+-- (see man devcontainer)
+---@return (string|nil) nil if no devcontainer_parent could be found otherwise
 -- the basic devcontainer command for the given type
-local function devcontainer_command(action, cwd)
-  devcontainer_root = folder_utils.get_root(cwd)
+local function devcontainer_command(action)
+  local devcontainer_root = folder_utils.get_root(config.toplevel)
   if devcontainer_root == nil then
     vim.notify("Unable to find devcontainer directory...", vim.log.levels.ERROR)
     return nil
@@ -94,26 +90,24 @@ local function devcontainer_command(action, cwd)
 end
 
 -- helper function to generate devcontainer bringup command
----@param cwd the current working directory. Used as a starting place to find 
--- .devcontainer directory
----@return nil if no devcontainer_parent could be found otherwise the 
+---@return (string|nil) nil if no devcontainer_parent could be found otherwise the
 -- devcontainer bringup command
-local function get_devcontainer_up_cmd(cwd)
-  local command = devcontainer_command("up", cwd)
+local function get_devcontainer_up_cmd()
+  local command = devcontainer_command("up")
   if command == nil then
     return command
   end
-  
+
   if config.remove_existing_container then
     command = command .. " --remove-existing-container"
   end
-	command = command .. " --update-remote-user-uid-default off"
+  command = command .. " --update-remote-user-uid-default off"
 
   if config.dotfiles_repository == "" or config.dotfiles_repository == nil then
     return command
   end
 
-  command = command .. " --dotfiles-repository '" .. config.dotfiles_repository 
+  command = command .. " --dotfiles-repository '" .. config.dotfiles_repository
   -- only include the branch if it exists
   if config.dotfiles_branch ~= "" and config.dotfiles_branch ~= nil then
     command = command .. " -b " .. config.dotfiles_branch
@@ -132,19 +126,18 @@ local function get_devcontainer_up_cmd(cwd)
 end
 
 -- issues command to bringup devcontainer
----@param cwd the current working directory. Used as a starting place to find 
--- .devcontainer directory
-function M.bringup(cwd)
-  local command = get_devcontainer_up_cmd(cwd)
+function M.bringup()
+  local command = get_devcontainer_up_cmd()
 
   if command == nil then
-    return 
+    return
   end
 
   if config.interactive then
     vim.ui.input(
-      {prompt=windows_utils.wrap_text(
-            "Spawning devcontainer with command: " .. command
+      {
+        prompt = windows_utils.wrap_text(
+          "Spawning devcontainer with command: " .. command
         ) .. "\n\n" .. "Press q to cancel or any other key to continue\n"
       },
       function(input)
@@ -164,11 +157,9 @@ function M.bringup(cwd)
 end
 
 -- execute the given cmd within the given devcontainer_parent
----@param cmd the command to issue in the devcontainer terminal
----@param cwd the current working directory. Used as a starting place to find 
--- .devcontainer directory
-function M.exec_cmd(cmd, cwd)
-  command = devcontainer_command("exec", cwd)
+---@param cmd (string) the command to issue in the devcontainer terminal
+function M.exec_cmd(cmd)
+  local command = devcontainer_command("exec")
   if command == nil then
     return
   end
@@ -178,15 +169,12 @@ function M.exec_cmd(cmd, cwd)
 end
 
 -- execute a given cmd within the given devcontainer_parent
----@param cwd the current working directory. Used as a starting place to find 
--- .devcontainer directory
----@param devcontainer_parent the location guess for .devcontainer directory
-function M.exec(cwd)
+function M.exec()
   vim.ui.input(
-    {prompt="Enter command:"},
+    { prompt = "Enter command:" },
     function(input)
       if input ~= nil then
-        M.exec_cmd(input, devcontainer_parent)
+        M.exec_cmd(input)
       end
     end
   )

lua/devcontainer_cli/folder_utils.lua

@@ -6,28 +6,28 @@ local function directory_exists(target_folder)
 end
 
 -- get the devcontainer path for the given directory
----@param directory the directory containing .devcontainer
----@return directory if a devcontainer exists within it or nil otherwise
+---@param directory (string) the directory containing .devcontainer
+---@return (string|nil) directory if a devcontainer exists within it or nil otherwise
 local function get_devcontainer_parent(directory)
   local devcontainer_directory = directory .. '/.devcontainer'
 
   if directory_exists(devcontainer_directory) then
     return directory
   end
 
-  return nil 
+  return nil
 end
 
 -- get the root directory the devcontainer given a directory
----@param directory to begin search in 
----@param toplevel flag indicating if the directory closes to root should be 
+---@param directory (string) to begin search in
+---@param toplevel (boolean) flag indicating if the directory closes to root should be
 -- returned
----@return the devcontainer directory closest to the root directory
+---@return (string|nil) the devcontainer directory closest to the root directory
 -- or the first if toplevel is true, and nil if no directory was found
 local function get_root_directory(directory, toplevel)
   local parent_directory = vim.fn.fnamemodify(directory, ':h')
-  local devcontainer_parent =  get_devcontainer_parent(directory)
-  
+  local devcontainer_parent = get_devcontainer_parent(directory)
+
   -- Base case: If we've reached the root directory
   if parent_directory == directory then
     return devcontainer_parent
@@ -49,9 +49,9 @@ end
 
 -- find the .devcontainer directory closes to the root upward from the current
 -- directory
----@param toplevel flag indicating if the directory closes to root should be 
+---@param toplevel (boolean) flag indicating if the directory closes to root should be
 -- returned
----@return the devcontainer directory closest to the root directory
+---@return (string|nil) the devcontainer directory closest to the root directory
 -- or the first if toplevel is true, and nil if no directory was found
 function M.get_root(toplevel)
   local current_directory = vim.fn.getcwd()

lua/devcontainer_cli/init.lua

@@ -5,7 +5,7 @@ local config = require("devcontainer_cli.config")
 local configured = false
 
 -- setup the devcontainer-cli plugin
----@param opts the options to set (see config/init.lua)
+---@param opts (table) the options to set (see config/init.lua)
 function M.setup(opts)
   config.setup(opts)
 
@@ -18,7 +18,7 @@ function M.setup(opts)
 
   -- Docker
   vim.api.nvim_create_user_command(
-    "DevcontainerUp", 
+    "DevcontainerUp",
     devcontainer_cli.up,
     {
       nargs = 0,
@@ -27,16 +27,16 @@ function M.setup(opts)
   )
 
   vim.api.nvim_create_user_command(
-    "DevcontainerExec", 
-    devcontainer_cli.exec, 
+    "DevcontainerExec",
+    devcontainer_cli.exec,
     {
       nargs = "?",
       desc = "Execute command in devcontainer.",
     }
   )
 
   vim.api.nvim_create_user_command(
-    "DevcontainerConnect", 
+    "DevcontainerConnect",
     devcontainer_cli.connect,
     {
       nargs = 0,

lua/devcontainer_cli/windows_utils.lua

@@ -3,11 +3,11 @@ local config = require("devcontainer_cli.config")
 local M = {}
 
 -- number of columns for displaying text
-local terminal_columns = config.terminal_columns 
+local terminal_columns = config.terminal_columns
 
 -- wrap the given text at max_width
----@param text the text to wrap
----@return the text wrapped
+---@param text (string) the text to wrap
+---@return (string) the text wrapped
 function M.wrap_text(text)
   local wrapped_lines = {}
   for line in text:gmatch("[^\n]+") do
@@ -26,13 +26,13 @@ function M.wrap_text(text)
 end
 
 -- create a floating window
----@param on_detach call back for when the window is detached
----@return the window and buffer numbers
-function M.open_floating_window(on_detach) 
+---@param on_detach (function) call back for when the window is detached
+---@return integer, integer the window and buffer numbers
+function M.open_floating_window(on_detach)
   local buf = vim.api.nvim_create_buf(false, true)
   vim.api.nvim_buf_set_option(buf, 'bufhidden', 'wipe')
   vim.api.nvim_buf_set_option(buf, 'filetype', 'devcontainer-cli')
-  vim.api.nvim_buf_set_keymap(buf, 'n', 'q', '<CMD>close<CR>', {}) 
+  vim.api.nvim_buf_set_keymap(buf, 'n', 'q', '<CMD>close<CR>', {})
   vim.api.nvim_buf_set_keymap(buf, 'n', '<esc>', '<CMD>close<CR>', {})
 
   local width = math.ceil(
@@ -52,25 +52,25 @@ function M.open_floating_window(on_detach)
     style = "minimal",
     border = "rounded",
     title = "devcontainer-cli",
-    title_pos = center,
+    title_pos = "center",
     -- noautocommand = false,
   })
   -- Attach autocommand for when the buffer is detached (closed)
   vim.api.nvim_buf_attach(buf, false, {
-      on_detach = on_detach
+    on_detach = on_detach
   })
 
   return win, buf
 end
 
 -- send text to the given buffer
----@param text the text to send
----@param buffer the buffer to send text to
+---@param text (string) the text to send
+---@param buffer (integer) the buffer to send text to
 function M.send_text(text, buffer)
-  local text = vim.split(wrap_text(text), "\n")
+  local text_tbl = vim.split(M.wrap_text(text), "\n")
 
   -- Set the content of the buffer
-  vim.api.nvim_buf_set_lines(buffer, 0, -1, false, text)
+  vim.api.nvim_buf_set_lines(buffer, 0, -1, false, text_tbl)
 end
 
 return M