From d97bcfa82c5cf4d6f8975b5a318bfb981dbb33ce Mon Sep 17 00:00:00 2001
From: oxaliq <git@oxaliq.net>
Date: Thu, 4 Apr 2024 17:41:27 -0400
Subject: [PATCH] add doc strings to cell and prop-net

---
 src/prop_net/cell.clj             | 13 ++++++++-----
 src/prop_net/naive_scalar_net.clj | 24 +++++++++++++-----------
 2 files changed, 21 insertions(+), 16 deletions(-)

diff --git a/src/prop_net/cell.clj b/src/prop_net/cell.clj
index 76ecf01..01048b8 100644
--- a/src/prop_net/cell.clj
+++ b/src/prop_net/cell.clj
@@ -5,10 +5,14 @@
   (= content nothing))
 
 (defprotocol ICell
-  (neighbors [this])
-  (content [this])
-  (add-content! [this increment])
-  (new-neighbor! [this new-neighbor]))
+  (neighbors [this]
+    "returns all propagators the cell serves as input to")
+  (content [this]
+    "returns current content")
+  (add-content! [this increment]
+    "adds content to cell if none is present")
+  (new-neighbor! [this new-neighbor]
+    "adds a new propagator as a neighbor to the cell"))
 
 (defrecord Cell
     [neighbors
@@ -34,7 +38,6 @@
     (let [old-neighbors (deref (:neighbors this))]
       (do (swap! (:neighbors this) conj new-neighbor)
           ;; add input
-          ;;(alert-propagator new-neighbor)
           :ok))))
 
 ;; returns an initialized cell
diff --git a/src/prop_net/naive_scalar_net.clj b/src/prop_net/naive_scalar_net.clj
index 3b0ea81..9707a9f 100644
--- a/src/prop_net/naive_scalar_net.clj
+++ b/src/prop_net/naive_scalar_net.clj
@@ -12,11 +12,11 @@
 (defprotocol IPropNet
   "A Naive Scalar Propagation Network. Add Cells and Propagators, wire them
   together and run. Cells should update based on wiring"
-  ;; introspect methods
-  (alerted-propagators [this]
-    "")
+  ;; -- introspect methods
+  (get-alerted-propagators [this]
+    "returns the keys of all propagators to be alerted on next scheduler cycle")
   (propagators-ever-alerted [this]
-    "")
+    "returns the keys of all propagators alerted since last scheduler initialization")
   (get-cells [this]
     "returns hash-map of all cells in network")
   (propagators [this]
@@ -30,15 +30,16 @@
 
   ;; mutation methods
   (add-cell! [this cell-key]
-    "")
+    "create a cell associated with a given key")
   (add-content-to-cell! [this cell-key content]
-    "")
-  (add-propagator! [this func]
-    "")
+    "add content to a cell at the given key, alerting the cell's neighboring
+     propagators, if any")
+  (add-propagator! [this prop-key func]
+    "create a propagator from the given function and associate it with the given key")
   (add-neighbor-to-cell! [this cell-key prop-key]
-    "")
+    "give the cell of the given cellkey a new neighbor of the given propagator key")
   (add-output-to-propagator! [this prop-key cell-key]
-    "")
+    "wire the output of a given propagator to the set-content! function of a given cell")
 
   ;; run methods
   (initialize-scheduler! [this]
@@ -61,8 +62,9 @@
      all-propagators
      propagators-ever-alerted]
   IPropNet
+
   ;; introspect methods INFO - complete
-  (alerted-propagators [net] (deref-get net :alerted-propagators))
+  (get-alerted-propagators [net] (deref-get net :alerted-propagators))
   (propagators-ever-alerted [net] (deref-get net :propagators-ever-alerted))
   (get-cells [net] (deref-get net :cells))
   (propagators [net] (deref-get net :all-propagators))