 
 ;; The core construct of measure is the registry.  To be useful, all
 ;; metrics are registered with a registry, which is typically a singleton.
-;; 
-;;
+;;
+;; The registry is a collection of named metrics.  Registries are useful both
+;; to group related sets of measurements, and as the vehicle through which
+;; measurements are reported.
 
 (defn registry
   "Creates and returns a new metrics registry."

;; Measure is a library that enables Clojure programs to track critical aspects of
;; their behavior.  Using idiomatic wrappers around Coda Hale's excellent
;; [Metrics][http://metrics.codahale.com] library, one can measure statistics from
;; simple counters to
;; exponentially-decaying histograms.
;;
;; 

(ns measure.core
  {}


;; Gauges can wrap either a function that returns a value or an atom.
(defn atom?
  "Returns true if the given value is an atom."
  [maybe-atom]
  (instance? clojure.lang.Atom maybe-atom))

(defn atom-or-fn
  "If the value is an atom, returns a no-arg function that derefs it.
   If the value is a function, it is returned unmodified.
   Otherwise, an exception is thrown."
  [val]
  (cond (atom? val) (fn [] @val)
        (fn? val) val
