             [zensols.actioncli.parse :as parse]
             [zensols.cisql.conf :as conf]))
 
-(def ^:private dbspec (atom nil))
-
-(def ^:private current-catalog (atom nil))
-
-(def ^:private db-info-data (atom nil))
-
-(def ^:private last-frame-label (atom nil))
-
-(def ^:private interrupt-execute-query (atom nil))
-
-(def ^:private query-thread (atom nil))
-
-(def ^:private query-no (atom 0))
+(def ^:private dbspec
+  "The jdbc package database spec and contains the DB host name, port etc."
+  (atom nil))
+
+(def ^:private current-catalog
+  "For catalog based systems this contains the name of the catalog."
+  (atom nil))
+
+(def ^:private db-info-data
+  "Information about the current database connection (i.e. user, URL)."
+  (atom nil))
+
+(def ^:private last-frame-label
+  "The last *label* (frame title) of the results frame of the last query."
+  (atom nil))
+
+(def ^:private interrupt-execute-query
+  "The state of the interrupt.  See [[interrupt]]."
+  (atom nil))
+
+(def ^:private query-thread
+  "The thread of the active query."
+  (atom nil))
+
+(def ^:private query-no
+  "The nth query, and used for thread syncs."
+  (atom 0))
 
 (defn- resolve-connection [db]
   (let [conn (jdbc/db-connection db)

       (display-result-set rs meta)
       (reset! last-frame-label (format "table: %s" table))))))

(defn- interrupt [signal]
  (log/debugf "interrupting with signal: %s" signal)
  (let [ieq @interrupt-execute-query]
    (println)

    (let [cols (.getColumnCount meta)]
      (take-while identity (repeatedly #(next-row cols))))))

(defn result-set-to-array
  "Return result set `rs` as an array of rows and column names.

Parameters:
  * **header**: the column header data
  * **rows**: a lazy list of maps each representing a row from the result set."
  [rs]
  (let [meta (.getMetaData rs)
        col-count (.getColumnCount meta)
        ;; must for SQLite: get headers before the result set is used up
