        (times "../")
        (apply str)))
 
-(defn add-paths [path-spec]
+(defn add-paths
+  "Returns a middleware function that adds paths to an `entity` based on `path-spec`. `path-spec` can use various `entity` keys by naming them in angle brackets (i.e. `\"posts/<year>/<month>/<title>.html\"`). Each key is stringified and [[lambda-blog.utils/sanitize]]d before including in the path."
+  [path-spec]
   (fn [entity]
     (let [p (fmt path-spec entity)]
       (assoc entity
              :path-to-root (path-to-root path-spec)
              :path (pathcat p)))))
 
-(defn collect-tags [{:keys [entries] :as ent}]
+(defn collect-tags
+  "Collects unique `tags` from each of the `entries` in the `ent`ity. Returns `ent`ity with collected tags stored under `tags`."
+  [{:keys [entries] :as ent}]
   (->> entries
        (map :tags)
        (apply union)
        (into #{})
        (assoc ent :tags)))
 
-(defn link [es]
+(defn link
+  "Links all entities in `es` by adding `:previous` and `:next` keys containing respective entities to each of them."
+  [es]
   (map (fn [prev curr next]
          (assoc curr
                 :previous prev

(ns lambda-blog.middleware
  (:refer-clojure :exclude [replace])
  (:require [clojure.pprint :refer [pprint]]
            [clojure.set :refer [union]]

       es
       (concat (next es) '(nil))))

(defn promote
  "Returns a middleware function that promotes all subkeys of a map under `what` key of an `entity` into the `entity`."
  [what]
  (fn [entity]
    (reduce (fn [e [k v]]
              (assoc e k v))
            entity
            (entity what))))

(defn inspect
  "Pretty prints an `entity` for debugging purposes. Returns unmodified `entity`."
  [entity]
  (log/debug (with-out-str (pprint entity)))
  entity)
