Updated context_manager/init.lua

- Added diagram for global context manager (GCM) structure.
- Removed local func@get_ctx_head (unused).
- Updated func@M.update:
	- function takes 2 parameter arguments (see docstring).
	- constructs new record for the given context in the GCM to keep
	  record of a newly constructed window buffer.
	- function updates the GCM with the new record.
- Updated func@M.flush:
	- handles for new structure of records in the GCM.
	- see docstring for info.

presser/context_manager/init.lua

@@ -1,16 +1,39 @@
 local a = vim.api
 local g = vim.g
 
+-- @Dev: The following table layout is the structure of contexts stored in the global manager.
+--
+-- vim.g.presser_buf_ctx = {
+--    <ctx> = {
+--        <int> {
+--            id = <win_id>,
+--            what = "Name of window" | id,
+--            allowed = true | false,
+--        },
+--        ...
+--    }
+-- }
+--
+
 -- setup a new global context manager for windows/buffers
 g.presser_buf_ctx = g.presser_buf_ctx or {} 
 
-
 local M = {}
 
-local get_ctx_head = function ( ctx )
-  return g.presser_buf_ctx[ctx][1]
-end
+-- @TODO: getters which might be useful
+--    + get_win_by_name
+--    + get_idx_from_win_id
+--    + get_next_allowed_win
+--    + get_prev_allowed_win
 
+
+-- @Description: Create a new context in the global context manager if it doesn't already exist.
+-- @Params:
+--    + `ctx` ~ A string which represents the name of the new context to be created.
+-- @Returns: nil. Updates the global context manager with a new context.
+--
+-- @Dev: note that this function shouldn't be responsible for multiple contexts existing in the global manager. Whilst
+-- it's possible that multiple contexts could exist, it would imply multiple UIs open at once, so unideal.
 M.create = function ( ctx )
   local c = g.presser_buf_ctx
   -- create specific context manager if it doesn't exist
@@ -20,26 +43,75 @@ M.create = function ( ctx )
   end
 end
 
--- :TODO: restructure function to allow for new data structure (see todo file)
-M.update = function ( ctx, data )
-  local c = g.presser_buf_ctx
+
+-- @Description: Update a context within the global context manager with a new buffer record. If the context doesn't
+-- exist, this function will guarantee that it does. If an ID for the window to be recorded in the context manager isn't
+-- provided, then this function errors. The table passed to `obj` must contain the key `id` for the function to succeed.
+-- The fields are as followed:
+--    + `id` ~ A number which is given when a new buffer window is constructed.
+--    + `what` ~ A string which gives the ID meaning; a label for the window (not related to buffer).
+--    + `allowed` ~ A boolean value which tells the context manager if the cursor is allowed in a window (virtually 
+--    disables the buffer).
+--
+--  `id` is the unique value to the record. Whilst `what` is a guaranteed value, its uniqueness isn't guaranteed in a
+--  given context. Since `what` can be used to fetch the associated `id` of the record, it should be unique from other
+--  records to prevent conflicts within a context to multiple window IDs.
+-- @Params:
+--    + `ctx` ~ A string representing the context which the record will be added to in the global context manager.
+--    + `obj` ~ A table holding one argument and two optionals.
+-- @Returns: bool.
+--
+-- @Dev: this function should require proper error handling to alert a dev when something really should be guaranteed,
+-- such as ID. (bool is fine to return, so perhaps error handling should be considered here for benefits).
+M.update = function ( ctx, obj )
   -- ensure that the context exists
-  if not c[ctx] then
-    M.create( ctx )
+--  if not g.presser_buf_ctx[ctx] then
+--    M.create( ctx )
+--  end
+  
+  if not obj.id then
+    print("[ERROR - context_manager]  cannot allocate window. No ID was provided.")
+    return false
   end
 
+  if obj.allowed == nil then
+    obj.allowed = true
+  end
+
+  -- construct new buffer record for context
+  local data = {
+    id = obj.id,
+    what = obj.what or obj.id,
+    allowed = obj.allowed,
+  }
+
+  -- read the global context buffer and add new buffer to context
+  local c = g.presser_buf_ctx
   table.insert(c[ctx], data)
+  
   g.presser_buf_ctx = c
+  return true
 end
 
+
+-- @Description: Flush the contents of the global context manager and destroy all associated windows and buffers to a
+-- context. Any information stored in the buffers is not saved during this process. Any such buffer contents should be
+-- handled before calling to flush.
+-- @Params: nil.
+-- @Returns: nil. Destroys all windows/buffers and clears the global context manager
+--
+-- @Dev: This is why it's important to guarantee that the IDs are stored in the context manager. They are required here
+-- to close the windows using the vim API calls, and force closing them too.
 M.flush = function ()
   for ctx, ctx_tbl in pairs( g.presser_buf_ctx ) do
-    for _, win_id in pairs( ctx_tbl ) do
-      a.nvim_win_close( win_id, true ) -- buffer contents are irrelevant in this context to save
+    for _, data in pairs( ctx_tbl ) do
+      print("Deleting:", _, data.id)
+      a.nvim_win_close( data.id, true ) -- buffer contents are irrelevant in this context to save
     end
   end
 
   g.presser_buf_ctx = {} -- clear the global context manager
 end
 
+
 return M