Replaced org document with hadock comments

src/Core/Node.hs

@@ -25,6 +25,25 @@ data InternalComment = InternalComment
   }
   deriving (Eq, Ord, Read, Show)
 
+{- | Node type
+ Note that the concept of a `Node` here is different from "node" in jbeam, when I mention JBeam nodes in this document I will explicitly call them JBeam nodes or call them Vertices.
+In this document when I refer to nodes I mean a datatype I which I have created to represent arrays, objects and scalar inside a JBeam structure.
+type declares a type synomom for a already existing type while data declares a new type.
+So a Node can be:
+- a Array and contain a vector of Nodes
+- a Object and contain a vector of Nodes
+- a ObjectKey and contain a 2-element tuple (also called a pair) where the the first element is the key and the second is the value
+- a String which contains a Text
+- a Number which contains a Scientific, a numeric data type which I really like to due to it unlike most other types in many programming languages can express any arbitrary-precision decimal number without rounding errors or losing precision.
+- a Bool which contains either True or False
+- a MultilineComment or SinglelineComment which contains a Text
+- a Null meaning that the node is empty
+
+So in fact Node is a recursive data structure, a type which references itself.
+Text is yet a another string type in Haskell which is good fit when doing appends or comparisons which I tend to do quite a lot in this codebase.
+I comptemplated using something like [OMap](https://hackage.haskell.org/package/ordered-containers-0.2.4/docs/Data-Map-Ordered.html) for the Object but then I realized that I do not only need support pairs of keys and values for the Object case, I also need to support the Object having Comments as direct children.
+The parser is currently written using attoaparsec but I are considering to migrate to Megaparsec since Megaparsec has better support implementing error messages which can be given to the end user.
+-}
 data Node
   = Array Array
   | Object Object

src/Core/NodeCursor.hs

@@ -21,6 +21,10 @@ data NodeBreadcrumb
   | ObjectIndexAndKey (Int, Text)
   deriving (Show)
 
+{- | node cursor
+A NodeCursor is a Sequence of breadcrumbs as we transcend deeper into the Node tree.
+A Seqeunce is good choice for NodeCursor since I need to compare the first element of the cursor and the path but when transcending the Node tree I need to append the current breadcrumb.
+-}
 newtype NodeCursor
   = NodeCursor (Seq NodeBreadcrumb)
   deriving stock (Show)
@@ -30,6 +34,9 @@ newCursor = NodeCursor Seq.empty
 
 type CursorFun a = NodeCursor -> Node -> a
 
+{- | applyCrumb
+This function takes a function f, a breadcrumb b, and a sequence of breadcrumbs wrapped in a NodeCursor, appends the the breadcrumb to the Sequence in the cursor and supplies the cursor to the function f. This is used whenever I update the Node tree to track where in the tree I am so, enabling checking whether I am updating at a certain point in the Node tree.
+-}
 applyCrumb :: NodeBreadcrumb -> NodeCursor -> CursorFun a -> Node -> a
 applyCrumb b (NodeCursor bs) f = f (NodeCursor $ bs :|> b)
 
@@ -43,6 +50,9 @@ applyObjCrumb key cursor _ = error $ unwords [errMsg, show key, show cursor]
 
 type SelCrumbCompFun = NP.NodeSelector -> NodeBreadcrumb -> Bool
 
+{- | compareSB
+Validate whether all the selectors match the corresponding breadcrumb, returning False if either Sequence exhausts prematurely.
+-}
 compareSB :: SelCrumbCompFun
 compareSB (NP.ObjectKey s) (ObjectIndexAndKey (_, k)) = s == k
 compareSB (NP.ObjectIndex s) (ObjectIndexAndKey (i, _)) = s == i

src/Core/NodePath.hs

@@ -20,6 +20,9 @@ data NodeSelector
   | ObjectIndex Int
   deriving (Eq, Ord, Read, Show)
 
+{- | node path
+A NodePath is a Sequence of selectors to that point out a certain point in a Node tree, either to point at as something when fetching it from Node or to point to something compare that I at a certain point when doing updates.
+-}
 newtype NodePath
   = NodePath (Seq NodeSelector)
   deriving stock (Read, Show)
@@ -33,6 +36,11 @@ extractValInKey :: N.Node -> Maybe N.Node
 extractValInKey (N.ObjectKey (_, val)) = Just val
 extractValInKey _ = Nothing
 
+{- | select
+Takes a Node and a selector.
+In case the selector matches nodes at a certain point in the tree.
+And queryNodes allows use to chain the Selectors as a NodePath and perform complex queries.
+-}
 select :: NodeSelector -> N.Node -> Maybe N.Node
 select (ArrayIndex i) (N.Array ns) = getNthElem 0 (V.toList ns)
   where