Update docstrings

Author: codeboost

.gitignore

@@ -4,4 +4,5 @@
 *.iml
 *.db
 .DS_Store
-*.xdb
+*.xdb
+target/

README.md

@@ -14,7 +14,7 @@
 
 ## Overview
 
-`xitdb-clj` is a database for efficiently storing and retrieving immutable, persistent data structures. 
+`xitdb-clj` is a embedded database for efficiently storing and retrieving immutable, persistent data structures. 
 
 It is a Clojure interface for [xitdb-java](https://github.com/radarroark/xitdb-java), 
 itself a port of [xitdb](https://github.com/radarroark/xitdb), written in Zig.
@@ -26,12 +26,11 @@ itself a port of [xitdb](https://github.com/radarroark/xitdb), written in Zig.
 - Embeddable, tiny library.
 - Supports writing to a file as well as purely in-memory use.
 - Each transaction (done via `swap!`) efficiently creates a new "copy" of the database, and past copies can still be read from.
-- Reading/Writing to the database is extremely efficient, only the necessary nodes are read or written.
+- Reading/Writing to the database is efficient, only the necessary nodes are read or written.
 - Thread safe. Multiple readers, one writer.
 - Append-only. The data you are writing is invisible to any reader until the very last step, when the top-level history header is updated.
-- No dependencies besides `clojure.core` and [xitdb-java](https://github.com/radarroark/xitdb-java).
 - All heavy lifting done by the bare-to-the-jvm java library.
-- Database files accessible from many other languages - all JVM based or languages which can natively interface with Zig (C, C++, Python, Rust, Go, etc)
+- Database files can be used from other languages, via [xitdb Java library](https://github.com/radarroark/xitdb-java) or the [xitdb Zig library](https://github.com/radarroark/xitdb)
 
 ## Architecture
 
@@ -175,10 +174,7 @@ values of the database, by setting the `*return-history?*` binding to `true`.
 Add to your `deps.edn`:
 
 ```clojure
-{:deps {org.clojure/clojure        {:mvn/version "1.12.0"}
-        io.github.radarroark/xitdb {:mvn/version "0.20.0"}
-        ;; Add your local xitdb-clj dependency here
-        }}
+{:deps {io.github.codeboost/xitdb-clj     {:mvn/version "0.1.0"}}}
 ```
 
 ## Examples

src/xitdb/db.clj

@@ -41,6 +41,9 @@
                                  (conversion/v->slot! cursor new-value))))
 
 (defn open-database
+  "Opens database `filename`.
+  If `filename` is `:memory`, returns a memory based db.
+  open-mode can be `r` or `rw`."
   [filename ^String open-mode]
   (let [core   (if (= filename :memory)
                  (CoreMemory. (RandomAccessMemory.))
@@ -58,7 +61,11 @@
     (conversion/v->slot! cursor v)))
 
 (defn xitdb-swap!
-  "Returns history index."
+  "Starts a new transaction and calls `f` with the value at root.
+  `f` will receive a XITDBWrite* type (db) and `args`.
+  Actions on the XITDBWrite* type (like `assoc`) will mutate it.
+  Return value of `f` is written at (root) cursor.
+  Returns the transaction history index."
   [db f & args]
   (let [history (db-history db)
         slot (.getSlot history -1)]
@@ -90,16 +97,22 @@
       (finally
         (.unlock lock)))))
 
-(defn- close-db-internal! [^Database db]
+(defn- close-db-internal!
+  "Closes the db file. Does nothing if it's a memory db"
+  [^Database db]
   (let [core (-> db .-core)]
     (when (instance? CoreFile core)
       (.close ^RandomAccessFile (-> db .-core .file)))))
 
 
-(defn ^ReadArrayList read-history [^Database db]
+(defn ^ReadArrayList read-history
+  "Returns the read only transaction history array."
+  [^Database db]
   (ReadArrayList. (-> db .rootCursor)))
 
-(defn history-index [xdb]
+(defn history-index
+  "Returns the current size of the transaction history array."
+  [xdb]
   (.count (read-history (-> xdb .tldbro .get))))
 
 (deftype XITDBDatabase [tldbro rwdb lock]
@@ -143,7 +156,11 @@
     (apply xitdb-swap-with-lock! (concat [this f x y] args))))
 
 (defn xit-db
-  ""
+  "Returns a new XITDBDatabase which can be used to query and transact data.
+  `filename` can be `:memory` or the name of a file on the filesystem.
+  If the file does not exist, it will be created.
+  The returned database handle can be used from multiple threads.
+  Reads can run in parallel, transactions (eg. `swap!`) will only allow one writer at a time."
   [filename]
   (if (= :memory filename)
     (let [memdb  (open-database :memory "rw")