   (:require [clj-http.lite.client :as client]
             [pl.danieljanus.tagsoup :as tagsoup]))
 
-(defn split-buildid [buildid]
+;; This library finds changesets given build dates (dates of the form YYYY-MM-DD)
+;; or build IDs (exact build timestamps of the form YYYYMMDDhhmmss).
+;;
+;; Example: obtaining a link to the changesets for build date 2015-05-03:
+;;
+;;     (println (find-build-changeset (find-date-buildid "2015-05-03" "mozilla-central") "mozilla-central"))
+;;
+;; Example: obtaining a link to changesets for buildid 20150503030209
+;;
+;;     (println (find-build-changeset "20150503030209" "mozilla-central"))
+
+(declare elements-by-tag-name)
+
+(defn- split-buildid
+  "Splits a buildid `buildid` into a dictionary with the date/time components as entries."
+  [buildid]
   {:y (Integer/parseInt (subs buildid 0 4)) :m (Integer/parseInt (subs buildid 4 6)) :d (Integer/parseInt (subs buildid 6 8))
    :hour (Integer/parseInt (subs buildid 8 10)) :min (Integer/parseInt (subs buildid 10 12)) :sec (Integer/parseInt (subs buildid 12 14))})
 
-(declare elements-by-tag-name)
-(defn list-elements-by-tag-name [children tag-name]
+(defn- list-elements-by-tag-name
+  "Obtains a list of all tags with tag name `tag-name` in `children`, a list of DOM elements in the form outputted by Tagsoup."
+  [children tag-name]
   (cond (empty? children) '()
         (vector? (first children)) (concat (elements-by-tag-name (first children) tag-name)
                                            (list-elements-by-tag-name (rest children) tag-name))
         :else '()))
-(defn elements-by-tag-name [tag tag-name]
+
+(defn- elements-by-tag-name
+  "Obtains a list of all tags with tag name `tag-name` in `tag`, a DOM in the form outputted by Tagsoup."
+  [tag tag-name]
   {:pre [(vector? tag) (keyword? tag-name)]}
   (if (= (first tag) :a)
     (cons tag (list-elements-by-tag-name (rest (rest tag)) tag-name))
     (list-elements-by-tag-name (rest (rest tag)) tag-name)))
 
-(defn find-build-dir-revision [build-dir-url]
+(defn- find-build-dir-revision
+  "Finds the hg revision associated with the build dir URL `build-dir-url`."
+  [build-dir-url]
   (let [response (tagsoup/parse build-dir-url)
         links (elements-by-tag-name response :a)
         text-file-links (filter #(re-find #"^firefox.*win32\.txt$" (get % 2)) links)]

        target-link (first (filter #(.startsWith (get % 2) date) build-dirs-links))
        [_ hour minute second] (re-find #"^\d{4}-\d{2}-\d{2}-(\d{2})-(\d{2})-(\d{2})" (get target-link 2))]
    (str year month day hour minute second)))

;(println (find-build-changeset (find-date-buildid "2015-05-03" "mozilla-central") "mozilla-central"))

          revision (re-find #"https:\/\/hg\.mozilla.*([0-9a-f]{12})$" revision-file)]
      (second revision))))

(defn- find-build-revision
  "Finds the hg revision of associated with the buildid `buildid` on channel `channel`."
  [buildid channel]
  (let [p (split-buildid buildid)
        build-dir-url (format "http://ftp.mozilla.org/pub/mozilla.org/firefox/nightly/%02d/%02d/%02d-%02d-%02d-%02d-%02d-%02d-%s/"
                    (:y p) (:m p) (:y p) (:m p) (:d p) (:hour p) (:min p) (:sec p) channel)]
    (find-build-dir-revision build-dir-url)))

(defn- find-preceding-build-revision
  "Find the first build made before buildid `buildid` on channel `channel`, and get its associated revision."
  [buildid channel]
  (let [p (split-buildid buildid)

        ;; Obtain a list of links to build directories in the desired channel
