update function doc comments

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)]

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
+  sql-fn      - a function that returns a JDBC-style vector containing a SELECT query
-                this view is refreshed"
+                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)))