Improved Javadoc for bulk write operations.

Author: jyemin

src/main/com/mongodb/BulkUpdateRequestBuilder.java

@@ -33,16 +33,17 @@ public class BulkUpdateRequestBuilder {
     }
 
     /**
-     * Adds an update request to replace one matching document to the bulk operation.
+     * Adds a request to replace one document in the collection that matches the query with which this builder was created.
      *
-     * @param document the replacement document
+     * @param document the replacement document, which must be structured just as a document you would insert.  It can not contain any
+     *                 update operators.
      */
     public void replaceOne(final DBObject document) {
         bulkWriteOperation.addRequest(new ReplaceRequest(query, upsert, document));
     }
 
     /**
-     * Adds an update request to update all matching documents to the bulk operation.
+     * Adds a request to update all documents in the collection that match the query with which this builder was created.
      *
      * @param update the update criteria
      */
@@ -51,7 +52,7 @@ public void update(final DBObject update) {
     }
 
     /**
-     * Adds an update request to update one matching document to the bulk operation.
+     * Adds a request to update one document in the collection that matches the query with which this builder was created.
      *
      * @param update the update criteria
      */

src/main/com/mongodb/BulkWriteOperation.java

@@ -22,7 +22,11 @@
 import static org.bson.util.Assertions.isTrue;
 
 /**
- * A bulk write operation.
+ * A bulk write operation.  A bulk write operation consists of an ordered or unordered collection of write requests,
+ * which can be any combination of inserts, updates, replaces, or removes.
+ *
+ * @see DBCollection#initializeOrderedBulkOperation()
+ * @see com.mongodb.DBCollection#initializeUnorderedBulkOperation()
  *
  * @since 2.12
  */
@@ -60,7 +64,8 @@ public void insert(final DBObject document) {
     }
 
     /**
-     * Start building a write request to add to the bulk write operation.
+     * Start building a write request to add to the bulk write operation.  The returned builder can be used to create an update, replace,
+     * or remove request with the given query.
      *
      * @param query the query for an update, replace or remove request
      * @return a builder for a single write request
@@ -71,7 +76,8 @@ public BulkWriteRequestBuilder find(final DBObject query) {
     }
 
     /**
-     * Execute the bulk write operation.
+     * Execute the bulk write operation with the default write concern of the collection from which this came.  Note that the
+     * continueOnError property of the write concern is ignored.
      *
      * @return the result of the bulk write operation.
      * @throws com.mongodb.BulkWriteException
@@ -85,9 +91,10 @@ public BulkWriteResult execute() {
     }
 
     /**
-     * Execute the bulk write operation with the given write concern.
+     * Execute the bulk write operation with the given write concern.  Note that the continueOnError property of the write concern is
+     * ignored.
      *
-     * @param writeConcern the write concern to apply to the bulk operation
+     * @param writeConcern the write concern to apply to the bulk operation.
      *
      * @return the result of the bulk write operation.
      * @throws com.mongodb.BulkWriteException

src/main/com/mongodb/BulkWriteRequestBuilder.java

@@ -31,30 +31,31 @@ public class BulkWriteRequestBuilder {
     }
 
     /**
-     * Adds a request to remove all matching documents to the bulk operation.
+     * Adds a request to remove all documents in the collection that match the query with which this builder was created.
      */
     public void remove() {
         bulkWriteOperation.addRequest(new RemoveRequest(query, true));
     }
 
     /**
-     * Adds a request to remove one matching documents to the bulk operation.
+     * Adds a request to remove one document in the collection that matches the query with which this builder was created.
      */
     public void removeOne() {
         bulkWriteOperation.addRequest(new RemoveRequest(query, false));
     }
 
     /**
-     * Adds a request to replace one matching documents to the bulk operation.
+     * Adds a request to replace one document in the collection that matches the query with which this builder was created.
      *
-     * @param document the replacement document
+     * @param document the replacement document, which must be structured just as a document you would insert.  It can not contain any
+     *                 update operators.
      */
     public void replaceOne(final DBObject document) {
         new BulkUpdateRequestBuilder(bulkWriteOperation, query, false).replaceOne(document);
     }
 
     /**
-     * Adds a request to replace one matching documents to the bulk operation.
+     * Adds a request to update all documents in the collection that match the query with which this builder was created.
      *
      * @param update the update criteria
      */
@@ -63,7 +64,7 @@ public void update(final DBObject update) {
     }
 
     /**
-     * Adds a request to update one matching documents to the bulk operation.
+     * Adds a request to update one document in the collection that matches the query with which this builder was created.
      *
      * @param update the update criteria
      */

src/main/com/mongodb/DBCollection.java

@@ -1619,8 +1619,17 @@ public CommandResult explainAggregate(List<DBObject> pipeline, AggregationOption
     public abstract List<Cursor> parallelScan(final ParallelScanOptions options);
 
     /**
-     * Creates a builder for an ordered bulk operation.  Write requests included in the bulk operations will be executed in order,
-     * and will halt on the first failure.
+     * Creates a builder for an ordered bulk write operation, consisting of an ordered collection of write requests,
+     * which can be any combination of inserts, updates, replaces, or removes. Write requests included in the bulk operations will be
+     * executed in order, and will halt on the first failure.
+     * <p>
+     * Note: While this bulk write operation will execute on MongoDB 2.4 servers and below, the writes will be performed one at a time,
+     * as that is the only way to preserve the semantics of the value returned from execution or the exception thrown.
+     * <p>
+     * Note: While a bulk write operation with a mix of inserts, updates, replaces, and removes is supported,
+     * the implementation will batch up consecutive requests of the same type and send them to the server one at a time.  For example,
+     * if a bulk write operation consists of 10 inserts followed by 5 updates, followed by 10 more inserts,
+     * it will result in three round trips to the server.
      *
      * @return the builder
      *
@@ -1631,8 +1640,12 @@ public BulkWriteOperation initializeOrderedBulkOperation() {
     }
 
     /**
-     * Creates a builder for an unordered bulk operation. Write requests included in the bulk operation will be executed in an undefined
-     * order, and all requests will be executed even if some fail.
+     * Creates a builder for an unordered bulk operation, consisting of an unordered collection of write requests,
+     * which can be any combination of inserts, updates, replaces, or removes. Write requests included in the bulk operation will be
+     * executed in an undefined  order, and all requests will be executed even if some fail.
+     * <p>
+     * Note: While this bulk write operation will execute on MongoDB 2.4 servers and below, the writes will be performed one at a time,
+     * as that is the only way to preserve the semantics of the value returned from execution or the exception thrown.
      *
      * @return the builder
      *
@@ -2014,7 +2027,7 @@ public ReadPreference getReadPreference(){
      */
     @Deprecated
     public void slaveOk(){
-        addOption( Bytes.QUERYOPTION_SLAVEOK );
+        addOption(Bytes.QUERYOPTION_SLAVEOK);
     }
 
     /**