doc comment updates

src/views/honeysql/core.clj

@@ -9,7 +9,10 @@
 (def hint-type :sql-table-name)
 
 (defmacro with-view-transaction
-  "Like jdbc's with-db-transaction, but sends view hints at end of 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)
@@ -33,12 +36,16 @@
     (j/execute! db (hsql/format hsql-map))))
 
 (defn vexec!
-  "Used to perform arbitrary insert/update/delete actions on the database,
-   while ensuring that view hints are sent to the view system.
+  "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
-   - action-map: the HoneySQL map for the insert/update/delete action"
+   - action-map: the HoneySQL map for the insert/update/delete SQL query"
   ([db namespace action-map]
    (let [results   (execute-honeysql! db action-map)
          hsql-hint (hint namespace (query-tables action-map) hint-type)]