Update change log

ChangeLog.md

@@ -1,3 +1,15 @@
+## Changes between 1.0.1 and 1.0.2
+
+No changes yet.
+
+
+## Changes between 1.0.0 and 1.0.1
+
+In the Monger 1.0.0 release jar, development dependencies were erroneously included in the jar. This affected
+projects using, for example, a different version of `clojure.core.cache`. This wasn't intentional and `1.0.1` is released
+to address the problem.
+
+
 ## Changes between 1.0.0-rc2 and 1.0.0
 
 ### Extended support for BSON serialization for Joda Time types

README.md

@@ -53,7 +53,7 @@ definition to your `pom.xml`:
 
 With Leiningen:
 
-    [com.novemberain/monger "1.0.0"]
+    [com.novemberain/monger "1.0.1"]
 
 
 With Maven:
@@ -61,7 +61,7 @@ With Maven:
     <dependency>
       <groupId>com.novemberain</groupId>
       <artifactId>monger</artifactId>
-      <version>1.0.0</version>
+      <version>1.0.1</version>
     </dependency>
 
 

project.clj

@@ -1,4 +1,4 @@
-(defproject com.novemberain/monger "1.0.0"
+(defproject com.novemberain/monger "1.0.2-SNAPSHOT"
   :description "Monger is a Clojure MongoDB client for a more civilized age: friendly, flexible and with batteries included"
   :min-lein-version "2.0.0"
   :license {:name "Eclipse Public License"}
@@ -23,18 +23,26 @@
   :source-paths      ["src/clojure"]
   :java-source-paths ["src/java"]
   :javac-options     ["-target" "1.6" "-source" "1.6"]  
-  :codox {:exclude [monger.internal.pagination]}
+  :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
+                    monger.ring.session-store]}
   :mailing-list {:name "clojure-mongodb"
                  :archive "https://groups.google.com/group/clojure-mongodb"
                  :post "clojure-mongodb@googlegroups.com"}
   :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]]
-                                   [ring/ring-core         "1.1.0"]]}}
+                                   [ring/ring-core         "1.1.0"]]
+                   :plugins [[codox "0.6.1"]]
+                   :codox {:sources ["src/clojure"]
+                           :output-dir "doc/api"}}}
   :aliases {"all" ["with-profile" "dev:dev,1.4:dev,1.5"]
             "ci"  ["with-profile" "dev:dev,1.4"]}
   :repositories {"sonatype" {:url "http://oss.sonatype.org/content/repositories/releases"

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]))
 
@@ -454,7 +467,12 @@
 
 (defn ensure-index
   "Creates an index on a set of fields, if one does not already exist.
-   This operation is optimized in the Java driver and is inexpensive in the case when an index already exists.
+   This operation is inexpensive in the case when an index already exists.
+
+   Options are:
+
+   :unique (boolean) to create a unique index
+   :name (string) to specify a custom index name and not rely on the generated one
 
    EXAMPLES
 
@@ -504,7 +522,7 @@
      (.dropIndex (.getCollection db collection) name)))
 
 (defn drop-indexes
-  "Drops an indices from this collection."
+  "Drops all indixes from this collection."
   ([^String collection]
      (.dropIndexes (.getCollection monger.core/*mongodb-database* collection)))
   ([^DB db ^String collection]

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
-       is in other monger.* namespaces, in particular monger.collection."}
+       fundamental functions that perform database/replica set connection, set default write concern, default database, performing commands
+       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
-  (:import (org.bson.types ObjectId))
+(ns ^{:doc "Provides clojure.data.json/Write-JSON protocol extension for MongoDB-specific types, such as
+            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
-  (:import (java.security SecureRandom) (java.math BigInteger) (org.bson.types ObjectId) (com.mongodb DBObject) (clojure.lang IPersistentMap) (java.util Map)))
+(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))
 
 ;;
 ;; API