Writing docs

docs/querying.md

@@ -0,0 +1,20 @@
+# Introduction
+
+Monger uses functional approach and wraps most of Java Driver's API into several namespaces:
+
+  - monger.core: Core methods (connection and database management)
+  - monger.collection: Collection operations (insert, find, count, update, save, remove, index etc.)
+  - monger.conversions: Helper methods to convert Clojure maps to DBObject and vice versa. Most of time not used directly, since you can get by manipulating hashes only.
+  - monger.query: Cursors and complex queries.
+  - monger.result: Auxilitary functions for getting the truth out of received MongoDB results.
+  - monger.util: Various utility methods.
+
+# Connecting to MongoDB
+
+Monger users several dynamic variables to simplify your common workflows:
+ - *mongodb-host*
+ - *mongodb-port*
+ - *mongodb-connection*
+ - *mongodb-database*
+ - *mongodb-write-concern* (we recommend to use WriteConcern/SAFE by default to make sure your data was written)
+

src/monger/core.clj

@@ -34,9 +34,11 @@
 ;;
 
 (defn ^Mongo connect
-  "Connects to MongoDB. When used without arguments, connects to *mongodb-host* and
+  "Connects to MongoDB. When used without arguments, connects to
-   *mongodb-test*.
 
+   Arguments:
+     :host (*mongodb-host* by default)
+     :port (*mongodb-port* by default)
 
    EXAMPLES
 
@@ -75,30 +77,22 @@
 
 
 (defn connect!
+  "Connect to MongoDB, save connection to *mongodb-connection* dynamic variable"
   ^Mongo [& args]
   (def ^:dynamic *mongodb-connection* (apply connect args)))
 
 
 (defn set-db!
+  "Set dynamic *mongodb-database* variable to given :db"
   [db]
   (def ^:dynamic *mongodb-database* db))
 
 
 (defn set-default-write-concern!
   [wc]
+  "Set dynamic *mongodb-write-concert* to :wc"
   (def ^:dynamic *mongodb-write-concern* wc))
 
-
-
-(defprotocol Countable
-  (count [this] "Returns size of the object"))
-
-(extend-protocol Countable
-  DBCursor
-  (count [^com.mongodb.DBCursor this]
-    (.count this)))
-
-
 (defn command
   "Available commands (please check MongoDB documentation for a complete list of commands for particular DB version.
    Returns CommandResult.
@@ -159,3 +153,12 @@
   "
   [^Map cmd]
   (.command ^DB *mongodb-database* ^DBObject (to-db-object cmd)))
+
+
+(defprotocol Countable
+  (count [this] "Returns size of the object"))
+
+(extend-protocol Countable
+  DBCursor
+  (count [^com.mongodb.DBCursor this]
+    (.count this)))

src/monger/query.clj

@@ -13,6 +13,8 @@
 
 (def ^{ :dynamic true } *query-collection*)
 
+;;
+;; Cursor/chain methods
 ;;
 ;; Monger query is an auxiliary construction that helps to create funciton chains through cursors.
 ;;   You can specify several chained actions that will be performed on the certain collection through

todo.md

@@ -0,0 +1,5 @@
+
+Operators:
+  - $where operator is missing
+  - no tests and no description for $bit operator
+  - move countable protocol out of core (?)