More docs

CHANGELOG.md

@@ -1,6 +1,10 @@
 # Change Log
 All notable changes to this project will be documented in this file. This change log follows the conventions of [keepachangelog.com](http://keepachangelog.com/).
 
+## [Unreleased]
+### Added
+- More documentation
+
 ## [0.3.0] - 2019-11-15
 ### Added
 - Added aggregate function
@@ -20,5 +24,6 @@ All notable changes to this project will be documented in this file. This change
 ### Added
 - Initial release
 
-[0.3.0]: https://github.com/gnarroway/mongo-driver-3/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/gnarroway/mongo-driver-3/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/gnarroway/mongo-driver-3/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/gnarroway/hato/compare/v0.1.0...v0.2.0

README.md

@@ -10,11 +10,12 @@ tasks convenient, whilst still allowing the underlying client to be configured v
 
 It was developed with the following goals:
 
+- Simple
 - Up to date with the latest driver versions
-- Minimal layer that doesn't block any functionality
+- Minimal layer that does not prevent access to the underlying driver
 - Consistent API across all functions
 - Configuration over macros
-- Simple
+
 
 
 ## Status
@@ -34,6 +35,85 @@ For Leinengen, add this to your project.clj:
 [mongo-driver-3 "0.3.0"]
 ```
 
+## Getting started
+
+We usually start by creating a client and connecting to a database with a connection string.
+`connect-to-db` is a convenience function that allows you to do this directly.
+
+```clojure
+(ns my.app
+  (:require [mongo-driver-3.client :as mcl]))
+
+(mcl/connect-to-db "mongodb://localhost:27017/my-db")
+; =>
+; {
+;  :client - a MongoClient instance
+;  :db - a Database that you can pass to all the collection functions
+; } 
+```
+
+You can also create a client and get a DB manually:
+
+```clojure 
+;; Calling create without an arg will try and connect to the default host/port.
+(def client (mcl/create "mongodb://localhost:27017")) 
+
+;; Create a db that you can pass around.
+(def db (mcl/get-db client "my-db:))
+```
+
+### Collection functions
+
+All the collection functions closely mirror the name of the corresponding java driver 
+[module](https://mongodb.github.io/mongo-java-driver/3.11/javadoc/com/mongodb/client/MongoCollection.html).
+
+They always take a db as the first argument, collection name as the second,
+and an optional map of options as the last. Full documentation of options can be found on 
+[cljdoc](https://cljdoc.org/d/mongo-driver-3/mongo-driver-3/CURRENT/api/mongo-driver-3.collection).
+
+As an example:
+
+```clojure 
+(ns my.app
+  (:require [mongo-driver-3.collection :as mc]))
+  
+;; Insert some documents
+(mc/insert-many db "test" [{:v "hello"} {:v "world"}])
+
+;; Count all documents
+(mc/count-documents db "test")
+; => 2
+
+;; Count with a query
+(mc/count-documents db "test" {:v "hello"})
+; => 1
+
+;; Find the documents, returning a seq
+(mc/find db "test' {} {:limit 1 :projection {:_id 0}})
+; => ({:v "hello"})
+
+;; Find the documents, returning the raw FindIterable response
+(mc/find db "test' {} {:raw? true})
+; => a MongoIterable
+
+;; Find a single document or return nil
+(mc/find-one db "test' {:v "world"} {:keywordize? false})
+; => {"v" "world"}
+```
+
+While most options are supported directly, sometimes you may need to configure an operation directly.
+In such cases, you can pass in the java options object.
+
+```clojure 
+;; These are equivalent
+(mc/rename db "test" "new-test" {:drop-target? true})
+
+(mc/rename db "test" "new-test" {:rename-collection-options (.dropTarget (RenameCollectionOptions.) true)})
+```
+
+Again, read the [docs](https://cljdoc.org/d/mongo-driver-3/mongo-driver-3/CURRENT/api/mongo-driver-3.collection)
+for full API documentation.
+
 ## License
 
 Released under the MIT License: http://www.opensource.org/licenses/mit-license.php

project.clj

@@ -1,4 +1,4 @@
-(defproject mongo-driver-3 "0.3.0"
+(defproject mongo-driver-3 "0.3.1-SNAPSHOT"
   :description "A Clojure wrapper for the Java MongoDB driver 3.11+."
   :url "https://github.com/gnarroway/mongo-driver-3"
   :license {:name         "The MIT License"

src/mongo_driver_3/collection.clj

@@ -12,7 +12,7 @@
 ;;; Conversions
 
 (defprotocol ConvertToDocument
-  (^Document document [input] "Convert some clojure to a Mongo Document"))
+  (^Document document [input] "Convert from clojure to Mongo Document"))
 
 (extend-protocol ConvertToDocument
   nil
@@ -47,7 +47,7 @@
     input))
 
 (defprotocol ConvertFromDocument
-  (from-document [input keywordize?] "Converts given Document to Clojure"))
+  (from-document [input keywordize?] "Converts Mongo Document to Clojure"))
 
 (extend-protocol ConvertFromDocument
   nil
@@ -87,12 +87,7 @@
    :snapshot     (ReadConcern/SNAPSHOT)})
 
 (defn ->ReadConcern
-  "Coerce `rc` into a ReadConcern if not nil.
+  "Coerce `rc` into a ReadConcern if not nil. See `collection` for usage."
-
-  Accepts a ReadConcern or kw corresponding to one:
-   [:available, :default, :linearizable, :local, :majority, :snapshot]
-
-  Invalid values will throw an exception."
   [rc]
   (when rc
     (if (instance? ReadConcern rc)
@@ -101,12 +96,7 @@
                                        (str "No match for read concern of " (name rc))))))))
 
 (defn ->ReadPreference
-  "Coerce `rp` into a ReadPreference if not nil.
+  "Coerce `rp` into a ReadPreference if not nil. See `collection` for usage."
-
-  Accepts a ReadPreference or a kw corresponding to one:
-    [:primary, :primaryPreferred, :secondary, :secondaryPreferred, :nearest]
-
-  Invalid values will throw an exception."
   [rp]
   (when rp
     (if (instance? ReadPreference rp)
@@ -114,17 +104,7 @@
       (ReadPreference/valueOf (name rp)))))
 
 (defn ->WriteConcern
-  "Coerce write-concern related options to a WriteConcern.
+  "Coerces write-concern related options to a WriteConcern. See `collection` for usage."
-
-  Accepts an options map:
-
-    :write-concern A WriteConcern or kw corresponding to one:
-      [:acknowledged, :journaled, :majority, :unacknowledged, :w1, :w2, :w3],
-      defaulting to :acknowledged, if some invalid option is provided.
-    :write-concern/w an int >= 0, controlling the number of replicas to acknowledge
-    :write-concern/w-timeout-ms How long to wait for secondaries to acknowledge before failing,
-      in milliseconds (0 means indefinite).
-    :write-concern/journal? If true, block until write operations have been committed to the journal."
   [{:keys [write-concern write-concern/w write-concern/w-timeout-ms write-concern/journal?]}]
   (when (some some? [write-concern w w-timeout-ms journal?])
     (let [wc (when write-concern
@@ -139,20 +119,25 @@
 (defn collection
   "Coerces `coll` to a MongoCollection with some options.
 
-  `db`   is a MongoDatabase
+  Arguments:
-  `coll` is a collection name or a MongoCollection. This is to provide flexibility in the use of
-    higher-level fns (e.g. `find-maps`), either in reuse of instances or in some more complex
-    configuration we do not directly support.
 
-  Accepts an options map:
+  - `db`   is a MongoDatabase
-    :read-preference
+  - `coll` is a collection name or a MongoCollection. This is to provide flexibility, either in reuse of
-    :read-concern
+    instances or in some more complex configuration we do not directly support.
-    :write-concern
+  - `opts` (optional), a map of:
-    :write-concern/w
+    - `:read-preference` Accepts a ReadPreference or a kw corresponding to one:
-    :write-concern/w-timeout-ms
+      [:primary, :primaryPreferred, :secondary, :secondaryPreferred, :nearest]
-    :write-concern/journal?
+      Invalid values will throw an exception.
-
+    - `:read-concern` Accepts a ReadConcern or kw corresponding to one:
-  See respective coercion functions for details (->ReadPreference, ->ReadConcern, ->WriteConcern)."
+      [:available, :default, :linearizable, :local, :majority, :snapshot]
+      Invalid values will throw an exception.
+    - `:write-concern` A WriteConcern or kw corresponding to one:
+      [:acknowledged, :journaled, :majority, :unacknowledged, :w1, :w2, :w3],
+      defaulting to :acknowledged, if some invalid option is provided.
+    - `:write-concern/w` an int >= 0, controlling the number of replicas to acknowledge
+    - `:write-concern/w-timeout-ms` How long to wait for secondaries to acknowledge before failing,
+       in milliseconds (0 means indefinite).
+    - `:write-concern/journal?` If true, block until write operations have been committed to the journal."
   ([^MongoDatabase db coll]
    (collection db coll {}))
   ([^MongoDatabase db coll opts]
@@ -166,7 +151,8 @@
 ;;; CRUD functions
 
 (defn aggregate
-  "Aggregates documents according to the specified aggregation pipeline and returns an AggregateIterable.
+  "Aggregates documents according to the specified aggregation pipeline and return a seq of maps,
+  unless configured otherwise..
 
   Arguments: