docs: improve type annotations and user documentation

lua/gitlab/actions/approvals.lua

@@ -4,24 +4,28 @@ local u = require("gitlab.utils")
 
 local M = {}
 
-local refresh_status_state = function(data)
-  u.notify(data.message, vim.log.levels.INFO)
+---Load mergeability and info data from Gitlab and update the Status window.
+local refresh_status_state = function()
   state.load_new_state("mergeability", function()
     state.load_new_state("info", function()
       require("gitlab.actions.summary").update_summary_details()
     end)
   end)
 end
 
+---Send the approval to Gitlab, notify user, and re-fresh state.
 M.approve = function()
   job.run_job("/mr/approve", "POST", nil, function(data)
-    refresh_status_state(data)
+    u.notify(data.message, vim.log.levels.INFO)
+    refresh_status_state()
   end)
 end
 
+---Send the approval revocation to Gitlab, notify user, and re-fresh state.
 M.revoke = function()
   job.run_job("/mr/revoke", "POST", nil, function(data)
-    refresh_status_state(data)
+    u.notify(data.message, vim.log.levels.INFO)
+    refresh_status_state()
   end)
 end
 

lua/gitlab/actions/assignees_and_reviewers.lua

@@ -1,5 +1,6 @@
 -- This module is responsible for the assignment of reviewers
 -- and assignees in Gitlab, those who must review an MR.
+
 local u = require("gitlab.utils")
 local job = require("gitlab.job")
 local List = require("gitlab.utils.list")
@@ -22,12 +23,18 @@ M.delete_reviewer = function()
   M.delete_popup("reviewer")
 end
 
+---Refresh the assignees and reviewers state with new data.
+---@param type "assignee"|"reviewer" The type of data to refresh
+---@param data table
+---@param message string Message from the Go server
 local refresh_user_state = function(type, data, message)
   u.notify(message, vim.log.levels.INFO)
   state.INFO[type] = data
   require("gitlab.actions.summary").update_summary_details()
 end
 
+---Prompt the user to select a new assignee/reviewer to add to the MR.
+---@param type "assignee"|"reviewer" The type of data to add to the MR
 M.add_popup = function(type)
   local plural = type .. "s"
   local current = state.INFO[plural]
@@ -50,6 +57,8 @@ M.add_popup = function(type)
   end)
 end
 
+---Prompt the user to select an existing assignee/reviewer to remove from the MR.
+---@param type "assignee"|"reviewer" The type of data to delete from the MR
 M.delete_popup = function(type)
   local plural = type .. "s"
   local current = state.INFO[plural]
@@ -71,6 +80,15 @@ M.delete_popup = function(type)
   end)
 end
 
+---@class HasId
+---@field id integer The ID of the item
+
+---Return a copy of `current` list of items without items in the `to_remove` list.
+---@generic T: HasId
+---@generic U: HasId
+---@param current T[] Original list of items
+---@param to_remove U[] List of items to remove
+---@return T[]
 M.filter_eligible = function(current, to_remove)
   local ids = u.extract(to_remove, "id")
   return List.new(current):filter(function(member)

lua/gitlab/actions/comment.lua

@@ -1,6 +1,6 @@
---- This module is responsible for creating new comments
---- in the reviewer's buffer. The reviewer will pass back
---- to this module the data required to make the API calls
+-- This module is responsible for creating new comments in the reviewer's buffer. The reviewer will
+-- pass back to this module the data required to make the API calls.
+
 local Popup = require("nui.popup")
 local Layout = require("nui.layout")
 local state = require("gitlab.state")
@@ -21,11 +21,10 @@ local M = {
   comment_popup = nil,
 }
 
----Fires the API that sends the comment data to the Go server, called when you "confirm" creation
----via the M.settings.keymaps.popup.perform_action keybinding
+---Fire the API to send the comment data to the Go server.
 ---@param text string comment text
 ---@param unlinked boolean if true, the comment is not linked to a line
----@param discussion_id string | nil The ID of the discussion to which the reply is responding, nil if not a reply
+---@param discussion_id? string The ID of the discussion when replying in a thread, otherwise nil
 local confirm_create_comment = function(text, unlinked, discussion_id)
   if text == nil then
     u.notify("Reviewer did not provide text of change", vim.log.levels.ERROR)
@@ -100,8 +99,7 @@ local confirm_create_comment = function(text, unlinked, discussion_id)
   end)
 end
 
--- This function will actually send the deletion to Gitlab when you make a selection,
--- and re-render the tree
+---Send comment deletion request to the Go server and re-render the tree.
 ---@param note_id integer
 ---@param discussion_id string
 ---@param unlinked boolean
@@ -113,7 +111,7 @@ M.confirm_delete_comment = function(note_id, discussion_id, unlinked)
   end)
 end
 
----This function sends the edited comment to the Go server
+---Send edited comment to the Go server.
 ---@param discussion_id string
 ---@param note_id integer
 ---@param unlinked boolean
@@ -133,13 +131,13 @@ end
 
 ---@class LayoutOpts
 ---@field unlinked boolean
----@field discussion_id string|nil
----@field reply boolean|nil
----@field file_name string|nil
+---@field discussion_id? string
+---@field reply? boolean
+---@field file_name? string
 
----This function sets up the layout and popups needed to create a comment, note and
----multi-line comment. It also sets up the basic keybindings for switching between
----window panes, and for the non-primary sections.
+---Set up the layout and popups needed to create a comment, note and multi-line comment.
+---Also set up basic keybindings for the non-primary sections, and for switching between
+---sections.
 ---@param opts LayoutOpts
 ---@return NuiLayout
 M.create_comment_layout = function(opts)
@@ -163,7 +161,7 @@ M.create_comment_layout = function(opts)
   local settings = u.merge(popup_settings, user_settings or {})
 
   local current_win = vim.api.nvim_get_current_win()
-  M.comment_popup = Popup(popup.create_popup_state(title, settings))
+  M.comment_popup = Popup(popup.create_popup_state({ title = title, user_settings = settings }))
   M.draft_popup = Popup(popup.create_box_popup_state("Draft", false, settings))
 
   local internal_layout = Layout.Box({
@@ -206,8 +204,8 @@ M.create_comment_layout = function(opts)
   return layout
 end
 
---- This function will open a comment popup in order to create a comment on the changed/updated
---- line in the current MR
+---Open a comment popup in order to create a comment on the changed/updated line in the
+---current MR.
 M.create_comment = function()
   M.location = Location.new()
   if not M.can_create_comment(false) then
@@ -218,8 +216,8 @@ M.create_comment = function()
   layout:mount()
 end
 
---- This function will open a multi-line comment popup in order to create a multi-line comment
---- on the changed/updated line in the current MR
+---Open a multi-line comment popup in order to create a multi-line comment on the
+---changed/updated line in the current MR.
 M.create_multiline_comment = function()
   M.location = Location.new()
   if not M.can_create_comment(true) then
@@ -231,16 +229,16 @@ M.create_multiline_comment = function()
   layout:mount()
 end
 
---- This function will open a a popup to create a "note" (e.g. unlinked comment)
---- on the changed/updated line in the current MR
+---Open a popup to create a "note" (e.g. unlinked comment) on the changed/updated line
+---in the current MR.
 M.create_note = function()
   local layout = M.create_comment_layout({ unlinked = true })
   layout:mount()
 end
 
 ---Given the current visually selected area of text, builds text to fill in the
 ---comment popup with a suggested change
----@return LineRange|nil
+---@return LineRange?
 local build_suggestion = function()
   local current_line = vim.api.nvim_win_get_cursor(0)[1]
   local range_length = M.location.visual_range.end_line - M.location.visual_range.start_line
@@ -273,9 +271,8 @@ local build_suggestion = function()
   return suggestion_lines
 end
 
---- This function will open a a popup to create a suggestion comment
---- on the changed/updated line in the current MR
---- See: https://docs.gitlab.com/ee/user/project/merge_requests/reviews/suggestions.html
+---Open a popup to create a suggestion comment on the changed/updated line in the current MR
+---See: https://docs.gitlab.com/ee/user/project/merge_requests/reviews/suggestions.html
 M.create_comment_suggestion = function()
   M.location = Location.new()
   if not M.can_create_comment(true) then
@@ -295,7 +292,7 @@ M.create_comment_suggestion = function()
   end)
 end
 
----Returns true if it's possible to create an Inline Comment
+---Return true if it's possible to create an inline comment.
 ---@param must_be_visual boolean True if current mode must be visual
 ---@return boolean
 M.can_create_comment = function(must_be_visual)
@@ -366,8 +363,8 @@ M.can_create_comment = function(must_be_visual)
   return true
 end
 
----Checks to see whether you are commenting on a valid buffer. The Diffview plugin names non-existent
----buffers as 'null'
+---Check whether user is commenting on a valid buffer.
+---Tightly coupled to how the Diffview plugin names non-existent buffers!
 ---@return boolean
 M.sha_exists = function()
   if vim.fn.expand("%") == "diffview://null" then