refactor: rename marshal maps and various comment rewordings

Signed-off-by: ldelossa <[email protected]>

lua/calltree/ui.lua

@@ -542,12 +542,14 @@ M.details = function()
 end
 
 -- auto_highlight will automatically highlight
--- the symbol under the cursor in symboltree
--- if set is true.
+-- symbols in the source code files when the symbol
+-- is selected in the symboltree.
 --
 -- if set is false it will remove any highlights
 -- in the source code's buffer.
 --
+-- this method is intended for use as an autocommand.
+--
 -- set : bool - whether to remove or set highlights
 -- for the symbol under the cursor in a symboltree.
 M.auto_highlight = function(set)
@@ -563,9 +565,12 @@ M.auto_highlight = function(set)
     au_hl.highlight(ctx.node, set, ctx.state)
 end
 
--- source tracking updates the symboltree ui
--- a source code line is encountered and a symbol
--- exists for the line.
+-- source_tracking is a method for keeping the cursor position
+-- and relevant highlighting within a source code file in sync
+-- with the cursor position and relevant highlighting within the
+-- symboltree, or vice versa.
+--
+-- this method is intended for use as an autocommand.
 M.source_tracking = function ()
     local ctx = ui_req_ctx()
     if ctx.state == nil then
@@ -586,7 +591,7 @@ M.source_tracking = function ()
     ctx.tree_handle = ctx.state.symboltree_handle
 
     -- if there's a direct match for this line, use this
-    local source_map = marshal.source_to_buf_line[ctx.tree_handle]
+    local source_map = marshal.source_line_map[ctx.tree_handle]
     if source_map == nil then
         return
     end
@@ -603,6 +608,7 @@ M.source_tracking = function ()
     if buf_lines == nil then
         return
     end
+---@diagnostic disable-next-line: redefined-local
     for line, node in pairs(buf_lines) do
         if ctx.linenr[1] >= node.document_symbol.range["start"].line
             and ctx.linenr[1] <= node.document_symbol.range["end"].line

lua/calltree/ui/marshal.lua

@@ -17,13 +17,31 @@ M.glyphs = {
 
 -- buf_line_map keeps a mapping between marshaled
 -- buffer lines and the node objects for a given tree.
+--
+-- the structure of this table is as follows:
+-- {
+--   tree_handle = {
+--      line_number = node,
+--      ...
+--   },
+--   ...
+-- }
 M.buf_line_map = {}
 
 -- maps source code lines to buffer lines
 -- for a given tree.
 --
 -- currently only useful for symboltree.
-M.source_to_buf_line = {}
+--
+-- the struture of this table is as follows:
+-- {
+--   tree_handle = {
+--      source_file_line_number = calltree_buffer_line_number
+--      ...
+--   }
+--   ...
+-- }
+M.source_line_map = {}
 
 -- marshal_node takes a node and marshals
 -- it into a UI buffer line.
@@ -162,7 +180,7 @@ function M.marshal_tree(buf_handle, lines, node, tree, virtual_text_lines, final
         virtual_text_lines = {}
         -- create a new line mapping
         M.buf_line_map[tree] = {}
-        M.source_to_buf_line[tree] = {}
+        M.source_line_map[tree] = {}
     end
     local line, virtual_text = M.marshal_node(node, final)
     table.insert(lines, line)
@@ -175,7 +193,7 @@ function M.marshal_tree(buf_handle, lines, node, tree, virtual_text_lines, final
     local loc = lsp_util.resolve_location(node)
     if loc ~= nil then
         local start_line = loc["range"]["start"].line
-        M.source_to_buf_line[tree][start_line+1] = #lines
+        M.source_line_map[tree][start_line+1] = #lines
     end
 
     -- if we are an expanded node or we are the root (always expand)