From 1c4c20fb61ea3224df3292f0386290a29dfa6f09 Mon Sep 17 00:00:00 2001
From: gered <gered@blarg.ca>
Date: Sun, 22 May 2016 15:42:18 -0400
Subject: [PATCH] update function doc comments

---
 src/views/sql/core.clj | 15 +++++++++++++++
 src/views/sql/view.clj |  5 +++--
 2 files changed, 18 insertions(+), 2 deletions(-)

diff --git a/src/views/sql/core.clj b/src/views/sql/core.clj
index dea96ad..583b2bc 100644
--- a/src/views/sql/core.clj
+++ b/src/views/sql/core.clj
@@ -63,6 +63,10 @@
   (:tables (query-info sql)))
 
 (defmacro with-view-transaction
+  "Works exactly like clojure.java.jdbc/with-db-transaction. Use this instead to wrap
+   vexec! calls which need to be run in a transaction. Holds all view system hints
+   generated by any vexec! calls within the transaction until the end, at which point
+   they are all sent to the view system."
   [binding & forms]
   (let [tvar (first binding)
         db   (second binding)
@@ -84,6 +88,17 @@
       (jdbc/execute! db sqlvec))))
 
 (defn vexec!
+  "Used to run any SQL insert/update/delete query on the database while ensuring
+   that view hints are sent to the view system to trigger any relevant view
+   refreshes. Use this instead of calling clojure.java.jdbc/execute! or
+   clojure.java.jdbc/insert!. If you need to perform an operation in a transaction
+   use with-view-transaction.
+
+   Arguments are:
+   - db: a clojure.java.jdbc database connection
+   - namespace (optional): a namespace that will be included in the hints sent out
+   - sqlvec: a JDBC-style vector containing a SQL query string followed by any
+             parameters for the query."
   ([db namespace [sql & params :as sqlvec]]
    (let [results (execute-sql! db sqlvec)
          hint    (views/hint namespace (query-tables sql) hint-type)]
diff --git a/src/views/sql/view.clj b/src/views/sql/view.clj
index 569daaa..107d285 100644
--- a/src/views/sql/view.clj
+++ b/src/views/sql/view.clj
@@ -32,7 +32,8 @@
 
   db-or-db-fn - either a database connection map, or a function that will get passed
                 a namespace and should return a database connection map
-  sql-fn      - a function that returns a sqlvec format SELECT query to be run when
-                this view is refreshed"
+  sql-fn      - a function that returns a JDBC-style vector containing a SELECT query
+                followed by any parameters. this query will be run whenever this view
+                needs to be refreshed."
   [id db-or-db-fn sql-fn & {:keys [row-fn]}]
   (SQLView. id db-or-db-fn sql-fn (or row-fn identity)))
\ No newline at end of file