From bce317fe95cf38d0430375381fe00b9aee839ad3 Mon Sep 17 00:00:00 2001
From: Pat Shields <yeoldefortran@gmail.com>
Date: Sun, 23 Mar 2014 16:29:57 -0400
Subject: [PATCH] Improve storage documentation.

---
 src/graf_znak/atom_storage.clj            |  3 ++-
 src/graf_znak/concurrent_hash_storage.clj | 11 +++++++++++
 2 files changed, 13 insertions(+), 1 deletion(-)

diff --git a/src/graf_znak/atom_storage.clj b/src/graf_znak/atom_storage.clj
index c8cb5f5..e4dc3dc 100644
--- a/src/graf_znak/atom_storage.clj
+++ b/src/graf_znak/atom_storage.clj
@@ -1,5 +1,6 @@
 (ns graf-znak.atom-storage
-  "Exposes the AtomStorage type which implements an atom backed HookStorage."
+  "Exposes the AtomStorage type which implements an atom backed HookStorage.
+   Expects pure accumulator functions."
   (:require [clojure.core.typed :refer :all]
             [graf-znak.hooks :refer :all]
             [graf-znak.accumulators :refer :all]))
diff --git a/src/graf_znak/concurrent_hash_storage.clj b/src/graf_znak/concurrent_hash_storage.clj
index 317de42..e81bea7 100644
--- a/src/graf_znak/concurrent_hash_storage.clj
+++ b/src/graf_znak/concurrent_hash_storage.clj
@@ -1,4 +1,12 @@
 (ns graf-znak.concurrent-hash-storage
+  "Exposes the ConcurrentHashStorage type which implements HookStorage backed
+   by a java ConcurrentHashMap.
+
+   Accumulations done on this storage are not transactional. They are expected
+   to mutate the existing state (specified originally by the accumulators
+   initial state). They accumulators should be thread safe.
+
+   Generally, this storage is only advisable if performance requires it."
   (:require [clojure.core.typed :refer :all]
             [graf-znak.hooks :refer :all]
             [graf-znak.accumulators :refer :all])
@@ -12,6 +20,8 @@
 ;; awful quite yet. Punting for now.
 (ann ^:no-check safe-put (All [x] (Fn [ConcurrentHashMap Object (Fn [-> x]) -> x])))
 (defn safe-put
+  "Like put if absent, but only actually loads the potential value after an
+   initial empty check."
   [^ConcurrentHashMap hashmap key val-factory]
   (when (not (.contains hashmap key))
     (let [v (val-factory)]
@@ -23,6 +33,7 @@
 
 (ann ^:no-check convert-groups (Fn [ConcurrentHashMap -> (Map Object Object)]))
 (defn convert-groups
+  "Brings hashmap backed groups into clojure data structures."
   [^ConcurrentHashMap storage]
   (into {}
         (map (fn>