         (chunk-samples [m-res ll-res c-size]
                        ?mod-h ?mod-v :> ?chunkid ?idx-seq))))
 
-;; TODO -- explain in docstring why ll-res, etc is important!
 (defn rain-months
-  "Returns all months from a directory of PREC/L datasets at the
-  supplied resolution, paired with their time periods."
+  "Cascalog subquery to extract all months from a directory of PREC/L
+  datasets at the supplied WGS84 spatial resolution, paired with time
+  periods appropriate for the supplied MODIS spatial
+  resolution. Source can be any tap that supplies files like
+  precl_mon_v1.0.lnx.2010.gri0.5m(.gz, optionally)."
   [m-res ll-res source]
   (<- [?dataset ?m-res ?period ?raindata]
-        (source ?filename ?file)
-        (unpack-rain [ll-res] ?file :> ?dataset ?month ?raindata)
-        (extract-period [m-res] ?filename ?month :> ?m-res ?period)))
-
-;; TODO -- update documentation
-(defmapop fancyindex [f coll]
-  [(apply vector (map (vec f) coll))])
-
-;; TODO -- update documentation
+      (source ?filename ?file)
+      (unpack-rain [ll-res] ?file :> ?dataset ?month ?raindata)
+      (extract-period [m-res] ?filename ?month :> ?m-res ?period)))
+
+(defmapop fancyindex [coll indices]
+  ^{:doc "Samples the supplied collection, returning the values at the
+  supplied indices within coll. Analogous to NumPy's [fancy
+  indexing](http://goo.gl/rZ4ri)."}
+  [(apply vector (map (vec coll) indices))])
+
+;; And, finally, the chunker. This subquery is analogous to the
+;; chunker found in `forma.hdf`. This is the only function that needs
+;; to be called, when processing new PRECL data.
+
 (defn rain-chunks
-  "Generates rain chunks for the given tiles, at the supplied
-  resolutions on each end of the chain."
+  "Cascalog subquery to fully process a WGS84 float array at the
+  supplied resolution (`ll-res`) into tuples suitable for comparison
+  to any MODIS dataset at the supplied modis resolution (`m-res`),
+  partitioned by the supplied chunk size."
   [m-res ll-res c-size tile-seq source]
   (let [indices (index-seqs m-res ll-res c-size tile-seq)
         precl (rain-months m-res ll-res source)]

  (let [bytes (get-bytes stream)]
    (rain-tuples ll-res (input-stream bytes))))

;; TODO -- update this. We need m-res because we need to act properly
;; on the datetime->period function, which currently depends on
;; resolution. We should probably change this to work on the time
;; period, like sixteens, days, etc.

;; Each PRECL filename contains the year from which the data is
;; sourced.

(defmapop [extract-period [m-res]]
  ^{:doc "Extracts the year from a NOAA PREC/L filename, assuming that
  the year is the only group of 4 digits. pairs it with the supplied
  month, and converts both into a time period, with units in months
  from the reference start date as defined in conversion.clj."}
  [filename month]
  (let [year (Integer/parseInt (first (re-find #"(\d{4})" filename)))]
    [m-res (datetime->period m-res year month)]))

(defn index-seqs
  "Takes a tile sequence and a couple of resolution parameters --
  returns translation indices for chunks within a tile, given the chunk size."
  [m-res ll-res c-size tile-seq]
  (let [source (memory-source-tap tile-seq)]
    (<- [?mod-h ?mod-v ?chunkid ?idx-seq]

;; NOAA PRECL data at 0.5 degree resolution, and processing them into
;; tuples suitable for machine learning against MODIS data.
;;
;; As in `forma.hdf`, the overall goal here is to process an NOAA
;; PREC/L dataset into tuples of the form
;;
;;     [?dataset ?res ?tileid ?tperiod ?chunkid ?chunk-pix]
