📚 Add documentation to objects and pointer map namespaces

backend/src/app/util/objects_map.clj

@@ -5,6 +5,16 @@
 ;; Copyright (c) KALEIDOS INC
 
 (ns app.util.objects-map
+  "Implements a specialized map-like data structure for store an UUID =>
+  OBJECT mappings. The main purpose of this data structure is be able
+  to serialize it on fressian as byte-array and have the ability to
+  decode each field separatelly without the need to decode the whole
+  map from the byte-array.
+
+  It works transparently, so no aditional dynamic vars are needed.  It
+  only works by reference equality and the hash-code is calculated
+  properly from each value."
+
   (:require
    ;; [app.common.logging :as l]
    [app.common.transit :as t]

backend/src/app/util/pointer_map.clj

@@ -5,6 +5,36 @@
 ;; Copyright (c) KALEIDOS INC
 
 (ns app.util.pointer-map
+  "Implements a map-like data structure that provides an entry point for
+  store its content in a separated blob storage.
+
+  By default it is not coupled with any storage mode and this is
+  externalized using specified entry points for inspect the current
+  available objects and hook the load data function.
+
+  Each object is identified by an UUID and metadata hashmap which can
+  be used to locate it in the storage layer. The hash code of the
+  object is always the hash of the UUID. And it always performs
+  equality by reference (I mean, you can't deep compare two pointers
+  map without completelly loads its contents and compare the content.
+
+  Each time you pass from not-modified to modified state, the id will
+  be regenerated, and is resposability of the hashmap user to properly
+  garbage collect the unused/unreferenced objects.
+
+  For properly work it requires some dynamic vars binded to
+  appropriate values:
+
+  - *load-fn*: when you instantatiate an object by ID, on first access
+    to the contents of the hash-map will try to load the real data by
+    calling the function binded to that dynamic var.
+
+  - *tracked*: when you instantiate an object or modify it, it is updated
+    on the atom (holding a hashmap) binded to this var; if no binding is
+    available, no tracking is performed. Tracking is needed for finally
+    persist to external storage all modified objects.
+  "
+
   (:require
    [app.common.logging :as l]
    [app.common.transit :as t]