                   ^clojure.lang.Seqable tags
                   ^String category])
 
+(defonce ^{:doc "An atom containing a map of paths to parses generated from
+                files at those paths. This atom is used to record parses created
+                during in the first step of parsing. Recording should take place
+                in the first step so that all parses have been recorded before
+                delays are executed."}
+  parses
+  (atom {}))
+
+(defn dissoc-parses
+  "Disassociates the given collection of paths from parses. This is useful
+  during development when a file is deleted from the input directory."
+  [deleted-paths]
+  (apply swap! parses dissoc deleted-paths))
+
+(defn record-parse
+  "Record the given parse at the given path in the parses atom."
+  [canonical-path ^Parse a-parse]
+  (swap! parses assoc canonical-path a-parse))
+
 (defonce ^{:doc "An atom containing a mapping of extensions (strings) to parse
-                functions. A parse function takes a java.io.File and writes
-                another file appropriately."}
+                functions. A parse function takes a java.io.File and returns
+                either a thunk or delay, which when invoked returns a sequence
+                of files. This two step invocation is necessary to achieve
+                features like tags."}
   parsers
   (atom {}))
-
-(defonce parses (atom {}))
-(defn dissoc-parses [deleted-paths]
-  (apply swap! parses dissoc deleted-paths))
-(defn record-parse [canonical-path ^Parse a-parse]
-  (swap! parses assoc canonical-path a-parse))
 
 (defn register
   "Register a parser for the given file extensions."

                       (repeat parser))))

(defn register-mappings
  [mappings]
  (doseq [[function-key new-function-key] mappings]
    (register new-function-key (@parsers (name function-key)))))

(ns incise.parsers.core
  (:require [incise.parsers.helpers :refer [extension]]
            (incise [config :as conf]
                    [utils :refer [directory?]])
            [clojure.java.io :refer [file]]
            [taoensso.timbre :refer [info]])
  (:import [java.io File]))

;; A Parse is simply a record definition which may be optionally used by incise
;; parsers. All HTML parsers use it as an intermediate format which gets stored
;; in the parses atom so they can be accessed globally during the final parsing
;; step. This is particularly useful for generating tags and the like.
(defrecord Parse [^String title
                  ^String extension
                  content
