Merge pull request #336

docs/includes/apiargs-MongoDBCollection-method-bulkWrite-option.yaml

@@ -6,11 +6,11 @@ arg_name: option
 name: ordered
 type: boolean
 description: |
-  If ``true``: when a single write fails, the operation returns without
-  performing the remaining writes.
+  If ``true``: when a single write fails, the operation will stop without
+  performing the remaining writes and throw an exception.
 
   If ``false``: when a single write fails, the operation will continue with the
-  remaining writes, if any.
+  remaining writes, if any, and throw an exception.
 
   The default is ``true``.
 interface: phpmethod

docs/includes/extracts-bulkwriteexception.yaml

+ref: bulkwriteexception-result
+content: |
+  If a :php:`MongoDB\\Driver\\Exception\\BulkWriteException
+  <mongodb-driver-exception-bulkwriteexception>` is thrown, users should call
+  :php:`getWriteResult() <mongodb-driver-writeexception.getwriteresult>` and
+  inspect the returned :php:`MongoDB\\Driver\\WriteResult
+  <mongodb-driver-writeresult>` object to determine the nature of the error.
+
+  For example, a write operation may have been successfully applied to the
+  primary server but failed to satisfy the write concern (e.g. replication took
+  too long). Alternatively, a write operation may have failed outright (e.g.
+  unique key violation).
+---
+ref: bulkwriteexception-ordered
+content: |
+  In the case of a bulk write, the result may indicate multiple successful write
+  operations and/or errors. If the ``ordered`` option is ``true``, some
+  operations may have succeeded before the first error was encountered and the
+  exception thrown. If the ``ordered`` option is ``false``, multiple errors may
+  have been encountered.
+...

docs/includes/extracts-error.yaml

+ref: error-driver-bulkwriteexception
+content: |
+  :php:`MongoDB\\Driver\\Exception\\BulkWriteException
+  <mongodb-driver-exception-bulkwriteexception>` for errors related to the write
+  operation. Users should inspect the value returned by :php:`getWriteResult()
+  <mongodb-driver-writeexception.getwriteresult>` to determine the nature of the
+  error.
+---
 ref: error-driver-invalidargumentexception
 content: |
   :php:`MongoDB\\Driver\\Exception\\InvalidArgumentException

docs/reference/method/MongoDBCollection-bulkWrite.txt

@@ -40,8 +40,15 @@ Errors/Exceptions
 
 .. include:: /includes/extracts/error-unsupportedexception.rst
 .. include:: /includes/extracts/error-invalidargumentexception.rst
+.. include:: /includes/extracts/error-driver-bulkwriteexception.rst
 .. include:: /includes/extracts/error-driver-runtimeexception.rst
 
+Behavior
+--------
+
+.. include:: /includes/extracts/bulkwriteexception-result.rst
+.. include:: /includes/extracts/bulkwriteexception-ordered.rst
+
 .. todo: add output and examples
 
 See Also

docs/reference/method/MongoDBCollection-deleteMany.txt

@@ -40,12 +40,14 @@ Errors/Exceptions
 
 .. include:: /includes/extracts/error-unsupportedexception.rst
 .. include:: /includes/extracts/error-invalidargumentexception.rst
+.. include:: /includes/extracts/error-driver-bulkwriteexception.rst
 .. include:: /includes/extracts/error-driver-runtimeexception.rst
 
 Behavior
 --------
 
 .. include:: /includes/extracts/note-bson-comparison.rst
+.. include:: /includes/extracts/bulkwriteexception-result.rst
 
 Example
 -------

docs/reference/method/MongoDBCollection-deleteOne.txt

@@ -42,12 +42,14 @@ Errors/Exceptions
 
 .. include:: /includes/extracts/error-unsupportedexception.rst
 .. include:: /includes/extracts/error-invalidargumentexception.rst
+.. include:: /includes/extracts/error-driver-bulkwriteexception.rst
 .. include:: /includes/extracts/error-driver-runtimeexception.rst
 
 Behavior
 --------
 
 .. include:: /includes/extracts/note-bson-comparison.rst
+.. include:: /includes/extracts/bulkwriteexception-result.rst
 
 Example
 -------

docs/reference/method/MongoDBCollection-insertMany.txt

@@ -39,8 +39,15 @@ Errors/Exceptions
 -----------------
 
 .. include:: /includes/extracts/error-invalidargumentexception.rst
+.. include:: /includes/extracts/error-driver-bulkwriteexception.rst
 .. include:: /includes/extracts/error-driver-runtimeexception.rst
 
+Behavior
+--------
+
+.. include:: /includes/extracts/bulkwriteexception-result.rst
+.. include:: /includes/extracts/bulkwriteexception-ordered.rst
+
 Example
 -------
 

docs/reference/method/MongoDBCollection-insertOne.txt

@@ -39,8 +39,14 @@ Errors/Exceptions
 -----------------
 
 .. include:: /includes/extracts/error-invalidargumentexception.rst
+.. include:: /includes/extracts/error-driver-bulkwriteexception.rst
 .. include:: /includes/extracts/error-driver-runtimeexception.rst
 
+Behavior
+--------
+
+.. include:: /includes/extracts/bulkwriteexception-result.rst
+
 Example
 -------
 

docs/reference/method/MongoDBCollection-replaceOne.txt

@@ -42,12 +42,14 @@ Errors/Exceptions
 
 .. include:: /includes/extracts/error-unsupportedexception.rst
 .. include:: /includes/extracts/error-invalidargumentexception.rst
+.. include:: /includes/extracts/error-driver-bulkwriteexception.rst
 .. include:: /includes/extracts/error-driver-runtimeexception.rst
 
 Behavior
 --------
 
 .. include:: /includes/extracts/note-bson-comparison.rst
+.. include:: /includes/extracts/bulkwriteexception-result.rst
 
 Example
 -------

docs/reference/method/MongoDBCollection-updateMany.txt

@@ -40,12 +40,14 @@ Errors/Exceptions
 
 .. include:: /includes/extracts/error-unsupportedexception.rst
 .. include:: /includes/extracts/error-invalidargumentexception.rst
+.. include:: /includes/extracts/error-driver-bulkwriteexception.rst
 .. include:: /includes/extracts/error-driver-runtimeexception.rst
 
 Behavior
 --------
 
 .. include:: /includes/extracts/note-bson-comparison.rst
+.. include:: /includes/extracts/bulkwriteexception-result.rst
 
 Examples
 --------

docs/reference/method/MongoDBCollection-updateOne.txt

@@ -42,12 +42,14 @@ Errors/Exceptions
 
 .. include:: /includes/extracts/error-unsupportedexception.rst
 .. include:: /includes/extracts/error-invalidargumentexception.rst
+.. include:: /includes/extracts/error-driver-bulkwriteexception.rst
 .. include:: /includes/extracts/error-driver-runtimeexception.rst
 
 Behavior
 --------
 
 .. include:: /includes/extracts/note-bson-comparison.rst
+.. include:: /includes/extracts/bulkwriteexception-result.rst
 
 Examples
 --------