Add missing docstrings / comments

src/yohoho/core.clj

@@ -55,6 +55,8 @@
 (defn db-get-item
   "Retrieve an item given its ID"
   [id]
+  ;; sql/* functions default to prefixing map keys with `#:items/`. Meh.
+  ;; Fortunately, builder-fn saves the day so we can have the output we want.
   (sql/get-by-id db :items id
                  {:builder-fn rs/as-unqualified-lower-maps}))
 
@@ -65,11 +67,14 @@
 
 ;; Handlers -------------------------------------------------------
 (defn ahoy-handler
+  "Health check"
   [_]
   {:status 200
    :body "Ahoy mate, the ship be sailin' alright"})
 
 (defn get-item-handler
+  "Return the item whose id is given as a path parameter
+   If it does not exist, HTTP 404 it is."
   [request]
   (let [id (get-in request [:path-params :id])
         item (db-get-item id)]
@@ -78,11 +83,16 @@
       :else       {:status 200 :body item})))
 
 (defn get-items-handler
+  "Return the list of every item
+   TODO: Add pagination"
   [_]
   {:status 200
    :body {:items (db-get-all-items)}})
 
 (defn create-item-handler
+  "Create a new item from request payload
+   Item id is autogenerated by the storage backend (SQLite)
+   Return the complete new item, id included."
   [request]
   (let [item (:body-params request)
         name (:name item)
@@ -113,7 +123,9 @@
 (def app
   (ring/ring-handler
    (ring/router
-    [["/ahoy"     {:get ahoy-handler}]
+    [;; Health check
+     ["/ahoy"     {:get ahoy-handler}]
+     ;; The real assignment: create and retrieve items
      ["/item/:id" {:get get-item-handler}]
      ["/items"    {:get get-items-handler
                    :post {:handler create-item-handler