 ;;; Response entity transformers.
 
 (defn to-html
-  "Encode response body as HTML."
+  "Transform response body into HTML."
   [response]
   (log/debug "responding with HTML")
   (let [template-fn (:template (meta response) html/default)]
     (update response :body template-fn)))
 
 (defn to-json
-  "Encode response body as JSON."
+  "Transform response body into JSON."
   [response]
   (log/debug "responding with json")
   (-> response
       (update :body json/encode)
       (assoc-in [:headers "Content-Type"] "application/json")))
 
+;; This is a list of supported types. By default a response will be
+;; produced as JSON, even if no accept media-ranges are provided.
+;; Even though this isn't technically correct, it's good-enough for
+;; the time being. It might be better to handle and empty accept header
+;; differently than an accept header that only request unsupported
+;; content-types.
+;;
+;; This uses a utility function provided by ring-accept instead
+;; of a macro so that debugging is somewhat easier.
 (def supported-types (accept :default to-json
                              "application/json" to-json
                              "text/html" to-html))
 
 (defn respond-with
-  ""
+  "Transform a data structure into a suitable representation."
   [request response]
   (supported-types request response))
 

(defn put-source
  "Handle request for creating a source and produce a response."
  [source-id {params :params :as req}]
  (let [source (merge {:id source-id :progress_name "created"} params)]
    (or (some->> (source/validate source)
                 (assoc {:status 403} :body))

  {:status 501})

(defn get-tile-specs
  "Get all tile-specs."
  []
  (log/debugf "get all tile-specs")
  (let [results (tile-spec/all)]
    {:status 200 :body results}))

(defn post-tile-spec
  "Create or update all tile-specs"
  [{body :body :as req}]
  (log/debugf "create or update %s tile specs" (count body))
  (let [saved (map #(index/index-spec! (tile-spec/insert %)) body)]
    {:status 200 :body {:saved (count saved)}}))

(defn put-tile-spec
  "Create or update a tile-spec."
  [ubid {body :body :as req}]
  (log/debugf "create or update tile-spec '%s' with %s" ubid body)
  (let [tile-spec (merge {:ubid ubid} body)]
    (or (some->> (tile-spec/validate tile-spec)
                 (assoc {:status 403} :body))
