             [s-html.print :refer [html->str]]
             [taoensso.timbre :as log]))
 
-(defn copy-dir! [{:keys [output-dir] :as ent} what where]
+(defn copy-dir!
+  "Copies `what` to `where` inside of the configured `output-dir`. Returns unmodified `ent`ity, but interacts with the filesystem."
+  [{:keys [output-dir] :as ent} what where]
   (let [to (pathcat output-dir where)]
     (log/info "Copying" what "to" to)
     (fs/copy-dir what to)
     ent))
 
-(defn clean-dir! [{:keys [output-dir] :as ent}]
+(defn clean-dir!
+  "Cleans the configured `output-dir`. Returns unmoified `ent`ity, but interacts with the filesystem."
+  [{:keys [output-dir] :as ent}]
   (let [d (pathcat output-dir)]
     (log/info "Cleaning" d)
     (fs/delete-dir d)
     ent))
 
-(defn update [entity key & funs]
+(defn update
+  "Returns `entity` with value under `key` modified by succesively applying `funs`."
+  [entity key & funs]
   (assoc entity
          key ((reduce comp (reverse funs))
               (entity key))))
 
-(defn update-all [entity key & funs]
+(defn update-all
+  "Returns `entity` with sequence under `key` modified by succesively applying `funs` to each of the elements."
+  [entity key & funs]
   (let [vs (entity key)]
     (assoc entity
            key

(ns lambda-blog.generator
  (:refer-clojure :exclude [update])
  (:require [clojure.java.io :refer [make-parents]]
            [lambda-blog.utils :refer [pathcat]]

         html->str
         (spit-file f))))

(defn generate!
  "Transforms a part of an `entity` under `key` into an HTML page using `template` with extra `args`. Returns unmodified `entity`, but interacts with the filesystem."
  [entity key template & args]
  (do-generate! template (merge entity (entity key)) args)
  entity)

(defn generate-all!
  "Transforms a sequence of values of an `entity` under `key` into HTML pages using `template` with extra `args`. Returns `entity` unmodified, but interacts with the filesystem."
  [entity key template & args]
  (doseq [ent (entity key)]
    (do-generate! template (merge entity ent) args))
  entity)

(defn read-dir
  "Reads a directory under `path` and parses each file using `parser`. Returns `entity` with parsed file contents sequence stored under `key`."
  [entity key path parser]
  (->> path
       fs/list-dir
       (map (fn [file]
              (log/info "Reading " file)
              (parser (slurp file))))
       (assoc entity key)))
