From 578673a0580498d84b60baa261360f98e6e745de Mon Sep 17 00:00:00 2001
From: Oleksandr Petrov <oleksandr.petrov@gmail.com>
Date: Fri, 25 Nov 2011 17:58:35 +0100
Subject: [PATCH] Writing docs

---
 docs/querying.md     | 20 ++++++++++++++++++++
 src/monger/core.clj  | 29 ++++++++++++++++-------------
 src/monger/query.clj |  2 ++
 todo.md              |  5 +++++
 4 files changed, 43 insertions(+), 13 deletions(-)
 create mode 100644 docs/querying.md
 create mode 100644 todo.md

diff --git a/docs/querying.md b/docs/querying.md
new file mode 100644
index 0000000..0506f4d
--- /dev/null
+++ b/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)
+
diff --git a/src/monger/core.clj b/src/monger/core.clj
index 0332946..510f64a 100644
--- a/src/monger/core.clj
+++ b/src/monger/core.clj
@@ -34,9 +34,11 @@
 ;;
 
 (defn ^Mongo connect
-  "Connects to MongoDB. When used without arguments, connects to *mongodb-host* and
-   *mongodb-test*.
+  "Connects to MongoDB. When used without arguments, connects to
 
+   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)))
diff --git a/src/monger/query.clj b/src/monger/query.clj
index a394e70..cdc9153 100644
--- a/src/monger/query.clj
+++ b/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
diff --git a/todo.md b/todo.md
new file mode 100644
index 0000000..9dfe90d
--- /dev/null
+++ b/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 (?)
\ No newline at end of file