Doc strings for namespaces

project.clj

@@ -24,6 +24,7 @@
   :java-source-paths ["src/java"]
   :javac-options     ["-target" "1.6" "-source" "1.6"]  
   :codox {:exclude [monger.internal.pagination
+                    monger.internal.fn
                     ;; these are not fully baked yet or have changes
                     ;; that are not entirely backwards compatible with 1.0. MK.
                     monger.testkit
@@ -34,7 +35,7 @@
   :profiles {:1.4 {:dependencies [[org.clojure/clojure "1.4.0"]]}
              :1.5 {:dependencies [[org.clojure/clojure "1.5.0-master-SNAPSHOT"]]}
              :dev {:resource-paths ["test/resources"]
-                   :dependencies  [[clj-time "0.4.2"              :exclusions [org.clojure/clojure]]
+                   :dependencies  [[clj-time "0.4.2"               :exclusions [org.clojure/clojure]]
                                    [org.clojure/data.json  "0.1.2" :exclusions [org.clojure/clojure]]
                                    [org.clojure/tools.cli  "0.2.1" :exclusions [org.clojure/clojure]]
                                    [org.clojure/core.cache "0.6.0" :exclusions [org.clojure/clojure]]

src/clojure/monger/cache.clj

@@ -1,4 +1,6 @@
-(ns ^{:doc "clojure.core.cache implementation(s) on top of MongoDB."
+(ns ^{:doc "clojure.core.cache implementation(s) on top of MongoDB.
+      
+            Related documentation guide: http://clojuremongodb.info/articles/integration.html"
       :author "Michael S. Klishin"}
   monger.cache
   (:require [monger.collection  :as mc]

src/clojure/monger/collection.clj

@@ -9,12 +9,25 @@
 ;; the terms of this license.
 ;; You must not remove this notice, or any other, from this software.
 
-(ns monger.collection
+(ns ^{:doc "Provides key functionality for interaction with MongoDB: inserting, querying, updating and deleting documents, performing Aggregation Framework
+            queries, creating and dropping indexes, creating collections and more.
+
+            For more advanced read queries, see monger.query.
+
+            Related documentation guides:
+
+            * http://clojuremongodb.info/articles/getting_started.html
+            * http://clojuremongodb.info/articles/inserting.html
+            * http://clojuremongodb.info/articles/querying.html
+            * http://clojuremongodb.info/articles/updating.html
+            * http://clojuremongodb.info/articles/deleting.html
+            * http://clojuremongodb.info/articles/aggregation.html"}
+  monger.collection
   (:refer-clojure :exclude [find remove count drop distinct empty?])
   (:import [com.mongodb Mongo DB DBCollection WriteResult DBObject WriteConcern DBCursor MapReduceCommand MapReduceCommand$OutputType]
            [java.util List Map]
            [clojure.lang IPersistentMap ISeq]
-           [org.bson.types ObjectId])
+           org.bson.types.ObjectId)
   (:require [monger core result])
   (:use     [monger.conversion]))
 

src/clojure/monger/command.clj

@@ -8,7 +8,16 @@
 ;; the terms of this license.
 ;; You must not remove this notice, or any other, from this software.
 
-(ns monger.command
+(ns ^{:doc "Provides convenience functions for performing most commonly used MongoDB commands.
+            For a lower-level API that gives maximum flexibility, see `monger.core/command`. To use
+            MongoDB 2.2 Aggregation Framework, see `monger.collection/aggregate`.
+
+            Related documentation guides:
+
+            * http://clojuremongodb.info/articles/commands.html
+            * http://clojuremongodb.info/articles/aggregation.html
+            * http://clojuremongodb.info/articles/mapreduce.html"}
+  monger.command
   (:require monger.core)
   (:use monger.conversion)
   (:import com.mongodb.DB))

src/clojure/monger/conversion.clj

@@ -21,7 +21,16 @@
 ;; OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 ;; THE SOFTWARE.
 
-(ns monger.conversion
+(ns ^{:doc "Provides functions that convert between MongoDB Java driver classes (DBObject, DBList) and Clojure
+            data structures (maps, collections). Most of the time, application developers won't need to use these
+            functions directly because Monger Query DSL and many other functions convert documents to Clojure sequences and
+            maps automatically. However, this namespace is part of the public API and guaranteed to be stable between minor releases.
+
+            Related documentation guides:
+
+            * http://clojuremongodb.info/articles/inserting.html
+            * http://clojuremongodb.info/articles/querying.html"}
+  monger.conversion
   (:import [com.mongodb DBObject BasicDBObject BasicDBList DBCursor]
            [clojure.lang IPersistentMap Named Keyword Ratio]
            [java.util List Map Date Set]

src/clojure/monger/core.clj

@@ -9,8 +9,14 @@
 
 (ns ^{:author "Michael S. Klishin"
       :doc "Thin idiomatic wrapper around MongoDB Java client. monger.core includes
-       fundamental functions that work with connections & databases. Most of functionality
+       fundamental functions that perform database/replica set connection, set default write concern, default database, performing commands
-       is in other monger.* namespaces, in particular monger.collection."}
+       and so on. Most of the functionality is in other monger.* namespaces, in particular monger.collection, monger.query and monger.gridfs
+
+       Related documentation guides:
+
+       * http://clojuremongodb.info/articles/connecting.html
+       * http://clojuremongodb.info/articles/commands.html
+       * http://clojuremongodb.info/articles/gridfs.html"}
   monger.core
   (:refer-clojure :exclude [count])
   (:use [monger.conversion])

src/clojure/monger/gridfs.clj

@@ -7,7 +7,12 @@
 ;; the terms of this license.
 ;; You must not remove this notice, or any other, from this software.
 
-(ns monger.gridfs
+(ns
+    ^{:doc "Provides functions and macros for working with GridFS: storing files in GridFS, streaming files from GridFS,
+            finding stored files.
+
+            Related documentation guide: http://clojuremongodb.info/articles/gridfs.html"}
+  monger.gridfs
   (:refer-clojure :exclude [remove find])
   (:require monger.core
             [clojure.java.io :as io])

src/clojure/monger/js.clj

@@ -17,5 +17,9 @@
 ;;
 
 (defn load-resource
+  "Loads a JavaScript resource (file from the classpath) and returns its content as a string.
+   The .js suffix at the end may be omitted.
+
+   Used primarily for map/reduce queries."
   (^String [^String path]
            (js/load-resource path)))

src/clojure/monger/json.clj

@@ -7,8 +7,10 @@
 ;; the terms of this license.
 ;; You must not remove this notice, or any other, from this software.
 
-(ns monger.json
+(ns ^{:doc "Provides clojure.data.json/Write-JSON protocol extension for MongoDB-specific types, such as
-  (:import (org.bson.types ObjectId))
+            org.bson.types.ObjectId"}
+  monger.json
+  (:import org.bson.types.ObjectId)
   (:require [clojure.data.json :as json]
             clojurewerkz.support.json))
 

src/clojure/monger/operators.clj

@@ -7,7 +7,12 @@
 ;; the terms of this license.
 ;; You must not remove this notice, or any other, from this software.
 
-(ns monger.operators)
+(ns ^{:doc "Provides vars that represent various MongoDB operators, for example, $gt or $in or $regex.
+            They can be passed in queries as strings but using vars from this namespace makes the code
+            a bit cleaner and closer to what you would see in a MongoDB shell query.
+
+            Related documentation guide: http://clojuremongodb.info/articles/querying.html"}
+  monger.operators)
 
 (defmacro ^{:private true} defoperator
   [operator]

src/clojure/monger/query.clj

@@ -7,7 +7,11 @@
 ;; the terms of this license.
 ;; You must not remove this notice, or any other, from this software.
 
-(ns monger.query
+(ns ^{:doc "Provides an expressive Query DSL that is very close to that in the Mongo shell (within reason).
+            This is the most flexible and recommended way to query with Monger. Queries can be composed, like in Korma.
+
+            Related documentation guide: http://clojuremongodb.info/articles/querying.html"}
+  monger.query
   (:refer-clojure :exclude [select find sort])
   (:require [monger.core]
             [monger.internal pagination])

src/clojure/monger/result.clj

@@ -7,7 +7,16 @@
 ;; the terms of this license.
 ;; You must not remove this notice, or any other, from this software.
 
-(ns monger.result
+(ns ^{:doc "Provides functions that determine if a query (or other database operation)
+            was successful or not.
+
+            Related documentation guides:
+
+            * http://clojuremongodb.info/articles/inserting.html
+            * http://clojuremongodb.info/articles/updating.html
+            * http://clojuremongodb.info/articles/commands.html
+            * http://clojuremongodb.info/articles/mapreduce.html"}
+  monger.result
   (:import [com.mongodb DBObject WriteResult MapReduceOutput]
            clojure.lang.IPersistentMap)
   (:require monger.conversion))

src/clojure/monger/util.clj

@@ -7,8 +7,13 @@
 ;; the terms of this license.
 ;; You must not remove this notice, or any other, from this software.
 
-(ns monger.util
+(ns ^{:doc "Provides various utility functions, primarily for working with document ids."} monger.util
-  (:import (java.security SecureRandom) (java.math BigInteger) (org.bson.types ObjectId) (com.mongodb DBObject) (clojure.lang IPersistentMap) (java.util Map)))
+  (:import java.security.SecureRandom
+           java.math.BigInteger
+           org.bson.types.ObjectId
+           com.mongodb.DBObject
+           clojure.lang.IPersistentMap
+           java.util.Map))
 
 ;;
 ;; API