Docstrings, one function call change, README update.

In the compiler there was one call to `table-name` which should have been
`field-name`.

1 files changed, 26 insertions, 4 deletions

diff --git a/src/clojure_sql/core.clj b/src/clojure_sql/core.clj
index 81c9c13..97cee93 100644
--- a/src/clojure_sql/core.clj
+++ b/src/clojure_sql/core.clj
@@ -41,21 +41,43 @@
     (pr (c/compile-select *database-type* query))))
 
 
-(defn run-query [query]
+(defn run-query
+  "Run a select query. Return value is determined by query executor."
+  [query]
   (assert *query-executor* "Cannot execute a query without a query executor")
   (*query-executor* :select (c/compile-select *database-type* query)))
 
-(defn insert! [query & records]
+(defn insert!
+  "Insert a number of records into a table, setting each column to the
+  corresponding value from the record. Return value is determined by
+  query executor."
+  [query & records]
   (assert *query-executor* "Cannot execute a query without a query executor")
   (let [compiled (apply c/compile-insert *database-type* query records)]
     (*query-executor* :insert compiled)))
 
-(defn update! [query partial-record]
+(-> (table :x)
+    (project {:id :uid})
+    (insert! {:uid 10}))
+
+(defn update!
+  "Update everything which would have been selected by the query,
+  setting each field in the query to the corresponding column in the
+  table. Return value is determined by query executor.
+
+  NOTE: if the map does not have a given key then this will result in
+  a NULL being included in the query. To avoid this restrict the query
+  with `project` before calling `update!`."
+
+  [query partial-record]
   (assert *query-executor* "Cannot execute a query without a query executor")
   (let [compiled (c/compile-update *database-type* query partial-record)]
     (*query-executor* :update compiled)))
 
-(defn delete! [query]
+(defn delete!
+  "Delete everything which would have been selected by the
+  query. Return value is determined by query executor."
+  [query]
   (assert *query-executor* "Cannot execute a query without a query executor")
   (let [compiled (c/compile-delete *database-type* query)]
     (*query-executor* :delete compiled)))