             [clojure.pprint :as pp]
             [cljs.source-map.base64-vlq :as base64-vlq]))
 
+;; =============================================================================
+;; All source map code in the file assumes the following in memory
+;; representation of source map data.
+;;
+;; { file { line { col } } }
+;;
+;; Each level is a sorted map. This simplifies merging ClojureScript source
+;; map information with source map information generated by Google Closure
+;; Compiler optimization.
+
 ;; -----------------------------------------------------------------------------
 ;; Utilities
 
-(defn indexed-sources [sources]
+(defn indexed-sources
+  "Take a seq of source file names and return a map from
+   file number to integer index."
+  [sources]
   (->> sources
     (map-indexed (fn [a b] [a b]))
     (reduce (fn [m [i v]] (assoc m v i)) {})))
 
-(defn source-compare [sources]
+(defn source-compare
+  "Take a seq of source file names and return a comparator
+   that can be used to construct a sorted map."
+  [sources]
   (let [sources (indexed-sources sources)]
     (fn [a b] (compare (sources a) (sources b)))))
 
 ;; -----------------------------------------------------------------------------
 ;; Decoding
 
-(defn seg->map [seg source-map]
+(defn seg->map
+  "Take a source map segment represented as a vector
+   and return a map."
+  [seg source-map]
   (let [[gcol source line col name] seg]
    {:gcol   gcol
     :source (nth (:sources source-map) source)

      (with-meta nseg {:name (+ name rname)})
      nseg)))

(defn update-result [result segmap gline]
  (let [{:keys [gcol source line col name]} segmap
        d {:gline gline
           :gcol gcol}

            (sorted-map)))))

(defn decode
  "Convert a v3 source map JSON object into a nested sorted map 
   organized as file, line, and column."
  ([source-map]
     (decode (:mappings source-map) source-map))
  ([mappings source-map]
