Added lots of comments and documentation 📘

lua/gitlab/comment.lua

@@ -11,13 +11,13 @@ local M                  = {}
 local comment_popup      = Popup(u.create_popup_state("Comment", "40%", "60%"))
 local edit_popup         = Popup(u.create_popup_state("Edit Comment", "80%", "80%"))
 
--- Function that fires to open the comment popup
+-- This function will open a comment popup in order to create a comment on the changed/updated line in the current MR
 M.create_comment         = function()
   comment_popup:mount()
   keymaps.set_popup_keymaps(comment_popup, M.confirm_create_comment)
 end
 
--- Actually sends the comment to Gitlab
+-- This function (keymaps.popup.perform_action) will send the comment to the Go server
 M.confirm_create_comment = function(text)
   local relative_file_path = u.get_relative_file_path()
   local current_line_number = u.get_current_line_number()
@@ -44,7 +44,7 @@ M.confirm_create_comment = function(text)
   end)
 end
 
--- Function to open the deletion popup
+-- This function (keymaps.discussion_tree.delete_comment) will trigger a popup prompting you to delete the current comment
 M.delete_comment         = function()
   local menu = Menu({
     position = "50%",
@@ -78,7 +78,8 @@ M.delete_comment         = function()
   menu:mount()
 end
 
--- Function to actually send the deletion to Gitlab
+-- This function will actually send the deletion to Gitlab
+-- when you make a selection
 M.send_deletion          = function(item)
   if item.text == "Confirm" then
     local current_node = state.tree:get_node()
@@ -106,7 +107,7 @@ M.send_deletion          = function(item)
   end
 end
 
--- Function that opens the edit popup from the discussion tree
+-- This function (keymaps.discussion_tree.edit_comment) will open the edit popup for the current comment in the discussion tree
 M.edit_comment           = function()
   local current_node = state.tree:get_node()
   local note_node = discussions.get_note_node(current_node)
@@ -129,7 +130,7 @@ M.edit_comment           = function()
   keymaps.set_popup_keymaps(edit_popup, M.send_edits(tostring(root_node.id), note_node.root_note_id or note_node.id))
 end
 
--- Function that actually makes the API call
+-- This function sends the edited comment to the Go server
 M.send_edits             = function(discussion_id, note_id)
   return function(text)
     local json_table = {
@@ -145,6 +146,7 @@ M.send_edits             = function(discussion_id, note_id)
   end
 end
 
+-- This comment (keymaps.discussion_tree.toggle_resolved) will toggle the resolved status of the current discussion and send the change to the Go server
 M.toggle_resolved        = function()
   local note = state.tree:get_node()
   if not note.resolvable then return end

lua/gitlab/discussions.lua

@@ -8,24 +8,8 @@ local keymaps              = require("gitlab.keymaps")
 
 local M                    = {}
 
-local replyPopup           = Popup(u.create_popup_state("Reply", "80%", "80%"))
-
-M.reply                    = function(discussion_id)
-  replyPopup:mount()
-  keymaps.set_popup_keymaps(replyPopup, M.send_reply(discussion_id))
-end
-
-M.send_reply               = function(discussion_id)
-  return function(text)
-    local jsonTable = { discussion_id = discussion_id, reply = text }
-    local json = vim.json.encode(jsonTable)
-    job.run_job("reply", "POST", json, function(data)
-      M.add_note_to_tree(data.note, discussion_id)
-    end)
-  end
-end
-
--- Places all of the discussions into a readable list
+-- Places all of the discussions into a readable tree
+-- in a split window
 M.list_discussions         = function()
   job.run_job("discussions", "GET", nil, function(data)
     if type(data.discussions) ~= "table" then
@@ -52,6 +36,26 @@ M.list_discussions         = function()
   end)
 end
 
+-- The reply popup will mount in a window when you trigger it (keymaps.discussion_tree.reply_to_comment) when hovering over a node in the discussion tree.
+local replyPopup           = Popup(u.create_popup_state("Reply", "80%", "80%"))
+M.reply                    = function(discussion_id)
+  replyPopup:mount()
+  keymaps.set_popup_keymaps(replyPopup, M.send_reply(discussion_id))
+end
+
+-- This function will send the reply to the Go API
+M.send_reply               = function(discussion_id)
+  return function(text)
+    local jsonTable = { discussion_id = discussion_id, reply = text }
+    local json = vim.json.encode(jsonTable)
+    job.run_job("reply", "POST", json, function(data)
+      M.add_note_to_tree(data.note, discussion_id)
+    end)
+  end
+end
+
+-- This function (keymaps.discussion_tree.jump_to_location) will
+-- jump you to the file and line where the comment was left
 M.jump_to_file             = function()
   local node = state.tree:get_node()
   if node == nil then return end
@@ -69,7 +73,6 @@ M.jump_to_file             = function()
 end
 
 M.set_tree_keymaps         = function(buf)
-  -- Jump to file location where comment was left
   vim.keymap.set('n', state.keymaps.discussion_tree.jump_to_location, function()
     M.jump_to_file()
   end, { buffer = true })
@@ -86,7 +89,7 @@ M.set_tree_keymaps         = function(buf)
     require("gitlab.comment").toggle_resolved()
   end, { buffer = true })
 
-  -- Expand/collapse the current node
+  -- Expands/collapses the current node
   vim.keymap.set('n', state.keymaps.discussion_tree.toggle_node, function()
       local node = state.tree:get_node()
       if node == nil then return end
@@ -117,6 +120,10 @@ M.set_tree_keymaps         = function(buf)
   end, { buffer = true })
 end
 
+--
+-- 🌲 Helper Functions
+--
+
 M.get_root_node            = function(node)
   if (not node.is_root) then
     local parent_id = node:get_parent_id()

lua/gitlab/init.lua

@@ -167,6 +167,8 @@ M.setPluginConfiguration = function(args)
 end
 
 -- Root Module Scope
+-- These functions are exposed when you call require("gitlab").some_function() from Neovim
+-- and are bound to keymaps provided in the setup function
 M.summary                = M.ensureState(summary.summary)
 M.approve                = M.ensureState(function() job.run_job("approve", "POST") end)
 M.revoke                 = M.ensureState(function() job.run_job("revoke", "POST") end)

lua/gitlab/job.lua

@@ -2,6 +2,8 @@ local Job   = require("plenary.job")
 local state = require("gitlab.state")
 local M     = {}
 
+-- This function is responsible for making API calls to the Go server and
+-- running the callbacks associated with those jobs when the JSON is returned
 M.run_job   = function(endpoint, method, body, callback)
   local args = { "-s", "-X", (method or "POST"), string.format("localhost:%s/", state.PORT) .. endpoint }
 

lua/gitlab/keymaps.lua

@@ -2,9 +2,9 @@ local u             = require("gitlab.utils")
 local state         = require("gitlab.state")
 local M             = {}
 
+-- Sets the keymaps for the popup window that's used for replies, the summary, etc
 M.set_popup_keymaps = function(popup, action)
   vim.keymap.set('n', state.keymaps.popup.exit, function() u.exit(popup) end, { buffer = true })
-  vim.keymap.set('n', ':', '', { buffer = true })
   if action ~= nil then
     vim.keymap.set('n', state.keymaps.popup.perform_action, function()
       local text = u.get_buffer_text(popup.bufnr)

lua/gitlab/state.lua

@@ -1,11 +1,16 @@
-local M             = {}
+local M      = {}
 
-M.BIN_PATH          = nil
-M.BIN               = nil
-M.PROJECT_ID        = nil
-M.ACTIVE_DISCUSSION = nil
-M.ACTIVE_NOTE       = nil
-M.keymaps           = {
+-- This is the global state that can be set from
+-- various places in the plugin. It all begins as
+-- uninitialized and is set by the setup/ensure function calls
+
+M.BIN_PATH   = nil -- Directory of the Go binary
+M.BIN        = nil -- Full path to the Go binary
+M.PROJECT_ID = nil -- Gitlab Project ID, set in .gitlab.nvim file
+M.INFO       = nil -- The basic information about the MR, set from "/info" endpoint
+
+-- These are the default keymaps for the plugin
+M.keymaps    = {
   popup = {
     exit = "<Esc>",
     perform_action = "<leader>s",

lua/gitlab/summary.lua

@@ -6,6 +6,7 @@ local keymaps          = require("gitlab.keymaps")
 local descriptionPopup = Popup(u.create_popup_state("Loading Description...", "80%", "80%"))
 local M                = {}
 
+-- The MR description will mount in a popup when this funciton is called
 M.summary              = function()
   descriptionPopup:mount()
   local currentBuffer = vim.api.nvim_get_current_buf()
@@ -23,6 +24,7 @@ M.summary              = function()
   end)
 end
 
+-- This function will PUT the new description to the Go server
 M.edit_description     = function(text)
   local jsonTable = { description = text }
   local json = vim.json.encode(jsonTable)