docs: reword docs

various documentation rewording and edits.

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

README.md

@@ -1,13 +1,13 @@
 ```
-/_____/\ /_______/\ /_/\     /_/\   /________/\/_____/\  /_____/\ /_____/\     
-\:::__\/ \::: _  \ \\:\ \    \:\ \  \__.::.__\/\:::_ \ \ \::::_\/_\::::_\/_    
- \:\ \  __\::(_)  \ \\:\ \    \:\ \    \::\ \   \:(_) ) )_\:\/___/\\:\/___/\   
-  \:\ \/_/\\:: __  \ \\:\ \____\:\ \____\::\ \   \: __ `\ \\::___\/_\::___\/_  
-   \:\_\ \ \\:.\ \  \ \\:\/___/\\:\/___/\\::\ \   \ \ `\ \ \\:\____/\\:\____/\ 
-    \_____\/ \__\/\__\/ \_____\/ \_____\/ \__\/    \_\/ \_\/ \_____\/ \_____\/ 
-                                                                               
-====================================================================================
-                      Neovim's missing call-hierarchy UI
+    /_____/\ /_______/\ /_/\     /_/\   /________/\/_____/\  /_____/\ /_____/\     
+    \:::__\/ \::: _  \ \\:\ \    \:\ \  \__.::.__\/\:::_ \ \ \::::_\/_\::::_\/_    
+     \:\ \  __\::(_)  \ \\:\ \    \:\ \    \::\ \   \:(_) ) )_\:\/___/\\:\/___/\   
+      \:\ \/_/\\:: __  \ \\:\ \____\:\ \____\::\ \   \: __ `\ \\::___\/_\::___\/_  
+       \:\_\ \ \\:.\ \  \ \\:\/___/\\:\/___/\\::\ \   \ \ `\ \ \\:\____/\\:\____/\ 
+        \_____\/ \__\/\__\/ \_____\/ \_____\/ \__\/    \_\/ \_\/ \_____\/ \_____\/ 
+                                                                                   
+    ==============================================================================
+                          Neovim's missing call-hierarchy UI
 ```
 
 # Calltree
@@ -26,16 +26,14 @@ requested.
 
 # Usage
 
-Usage is similar to any other lua plugin. 
-
-# Get it
+## Get it
 
 Plug:
 ```
  Plug 'ldelossa/calltree.nvim'
 ```
 
-# Set it
+## Set it
 
 Call the setup function from anywhere you configure your plugins from.
 
@@ -44,7 +42,7 @@ Configuration dictionary is explained in ./doc/calltree.txt (:h calltree-config)
 require('calltree').setup({})
 ```
 
-# Use it
+## Use it
 
 The setup function hooks directly into the "textDocument/incomingCalls" and "textDocument/outgoingCalls" 
 LSP handlers. 
@@ -63,7 +61,7 @@ hierarchy in an intuitative way.
 
 Use ":CTExpand" and ":CTCollapse" to achieve this.
 
-See (:h calltree-commands) for a list of commands.
+Check out (:h calltree) for all the details.
 
 # Features
 
@@ -73,11 +71,11 @@ There are a few features which add a bit more to the basic calltree usage.
 
 ## Switching Directions
 
-The ":CTSwitch" command will focus and inverse the call tree for the symbol under the curosor. 
+The ":CTSwitch" command will focus and inverse the call tree (move from outgoing to incoming for example) for the symbol under the curosor. 
 
 ## Focusing
 
-The ":CTFocus" command will reparent the symbol under the cursor, making it root. 
+The ":CTFocus" command will re-parent the symbol under the cursor, making it root. 
 
 From there you can continue down the call tree.
 

doc/calltree.txt

@@ -19,7 +19,8 @@ CONTENTS                                                         *calltree-conte
   1. Intro........................................|calltree-intro|
   2. Usage........................................|caltree-usage|
   3. Commands.....................................|calltree-commands|
-  3. Config.......................................|calltree-config|
+  4. Mappings.....................................|calltree-mappings|
+  5. Config.......................................|calltree-config|
 
 ====================================================================================
 INTRODUCTION                                                        *calltree-intro*
@@ -99,6 +100,23 @@ Calltree exports several commands for manipulating the calltree UI.
     Echos the current calltree in lua dictonary syntax. 
     Useful for debugging.
 
+====================================================================================
+MAPPINGS                                                         *calltree-mappings*
+
+Since all of calltree's usage happens within it's own buffer, its pretty safe to assign this buffer a default keymap. 
+
+This does not stop you from mapping *calltree-commands* to your own liking.
+
+The default buffer mapping is set via lua and should feel familiar if you use vim folds.
+
+    local opts = {silent=true}
+    vim.api.nvim_buf_set_keymap(M.buffer_handle, "n", "zo", ":CTExpand<CR>", opts)
+    vim.api.nvim_buf_set_keymap(M.buffer_handle, "n", "zc", ":CTCollapse<CR>", opts)
+    vim.api.nvim_buf_set_keymap(M.buffer_handle, "n", "<CR>", ":CTJump<CR>", opts)
+    vim.api.nvim_buf_set_keymap(M.buffer_handle, "n", "f", ":CTFocus<CR>", opts)
+    vim.api.nvim_buf_set_keymap(M.buffer_handle, "n", "i", ":CTHover<CR>", opts)
+    vim.api.nvim_buf_set_keymap(M.buffer_handle, "n", "s", ":CTSwitch<CR>", opts)
+
 ====================================================================================
 CONFIG                                                             *calltree-config*
 
@@ -131,6 +149,3 @@ The config table is described below:
         -- "codicon"        - Use VSCode codicon icon set for symbol types (requires patched font)
         icons = "none"
     }
-
-
-

lua/calltree/tree.lua

@@ -130,6 +130,8 @@ end
 
 -- recursive_dpt_compute traverses the tree
 -- and flattens it into out depth_table
+--
+-- node : Node - calltree's root node.
 local function _recursive_dpt_compute(node)
     local depth = node.depth
     if M.depth_table[depth] == nil then
@@ -179,6 +181,11 @@ end
 
 -- remove subtree will remove the subtree of the
 -- provided node, leaving the root node present.
+--
+-- node : Node - the parent node who's subtree
+--               is to be removed
+-- root : bool - should be "true", indicator that
+--               recursion is at the root node.
 function M.remove_subtree(node, root)
     -- recurse to leafs
     for _, child in ipairs(node.children) do
@@ -205,6 +212,10 @@ end
 -- creating a new calltree rooted at node.
 --
 -- the subtree from node down is preserved.
+--
+-- depth : int  - indicator of the incoming node's depth
+--                useful for understanding when recursion is done.
+-- node  : Node - the Node object being reparented.
 function M.reparent_node(depth, node)
     -- we are the new root, dump the current root_node and
     -- set yourself
@@ -215,9 +226,9 @@ function M.reparent_node(depth, node)
     -- recurse to leafs
     for _, child in ipairs(node.children) do
         M.reparent_node(depth+1, child)
+        -- recursion done, update your depth
         child.depth = depth+1
     end
-    -- recursion done, update your depth
     if depth == 0 then
         -- we are the root node, refresh depth_table with
         -- new tree.

lua/calltree/ui.lua

@@ -17,14 +17,13 @@ local direction_map = {
 M.buffer_handle = nil
 -- the global calltree window
 M.win_handle = nil
--- the last tabpage our outline ui was
--- on
+-- the last tabpage our outline ui was on
 M.win_tabpage = nil
 -- the active lsp clients attached to the
 -- buffer invoking the call tree.
 M.active_lsp_clients = nil
--- defines whether the call window shows
--- incoming (from) calls or outgoing (to)
+-- determines the direction (incoming or outgoing) of calls
+-- the calltree is showing.
 M.direction = nil
 -- the window in which the calltree was invoked.
 M.invoking_win_handle = nil
@@ -115,6 +114,9 @@ M.close = function()
 end
 
 -- encodes a tree node into a ui line
+-- node : Node - the node to enode into a buffer
+--               line.
+-- returns string
 M.encode_node_to_line = function(node)
     local str = ""
     local glyph
@@ -141,6 +143,8 @@ M.encode_node_to_line = function(node)
 end
 
 -- decodes a ui line into a tree node.
+-- line : string - the line to encode into a tree.Node
+-- returns tree.Node
 M.decode_line_to_node = function(line)
     -- number of characters up to the expand symbol encode
     -- the node's tree depth.
@@ -169,6 +173,11 @@ end
 --
 -- preorder traveral will print the outline as a
 -- user would expect.
+--
+-- lines : string[] - recursive accumlator of buffer lines to write
+--                  - call this function with an empty table {}
+-- node : tree.Node - the node to write to the tree. call this function
+--                    with tree.root_node typically.
 M.write_tree = function(lines, node)
     -- this is the root - ensure the outline buffer
     -- is setup.
@@ -235,6 +244,9 @@ M.expand = function()
     )
 end
 
+-- focus will reparent the calltree to the symbol under
+-- the cursor, creating a calltree with the symbol
+-- as root.
 M.focus = function()
     local line   = vim.api.nvim_get_current_line()
     local node = M.decode_line_to_node(line)
@@ -247,6 +259,8 @@ M.focus = function()
     M.write_tree({}, tree.root_node)
 end
 
+-- switch_direction will focus the symbol under the
+-- cursor and then invert the call hierarchy direction.
 M.switch_direction = function()
     local line = vim.api.nvim_get_current_line()
     local node = M.decode_line_to_node(line)
@@ -352,6 +366,8 @@ M.jump = function()
     vim.lsp.util.jump_to_location(location)
 end
 
+-- hover will show LSP hover information for the symbol
+-- under the cursor.
 M.hover = function()
     local line = vim.api.nvim_get_current_line()
     local node = M.decode_line_to_node(line)