PHPLIB-246: Document BulkWriteException thrown by write operations

Clarify how the "ordered" option may impact bulk write operations. Also advise users to inspect the BulkWriteException's WriteResult to determine the nature of the error.

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
 --------