 
 ;; 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


;; The core construct of measure is the registry.  To be useful, all
;; metrics are registered with a registry, which is typically a singleton.
;; 
;;

(defn registry
  "Creates and returns a new metrics registry."

  Timer
  (value [t] (.getCount t)))

;; Some metrics (histograms, meters, and timers) provide non-scalar information, and `value` is
;; insufficient for these types.  Meters expose rates, histograms expose distribution snapshots,
;; and timers expose both.

(defn rates
  "Gets the current rate of events for the given measurement."
  [^Metered meter-or-timer]
  {:count (.getCount meter-or-timer)
   :15-minute-rate (.getFifteenMinuteRate meter-or-timer)
   :5-minute-rate (.getFiveMinuteRate meter-or-timer)
   :1-minute-rate (.getOneMinuteRate meter-or-timer)
   :mean-rate (.getMeanRate meter-or-timer)})

(defn snapshot
  "Gets a snapshot of the current distribution for the given measurement."
  [^Sampling histogram-or-timer]
  (let [s (.getSnapshot histogram-or-timer)]
    {:size (.size s)
     :min (.getMin s)
     :max (.getMax s)
