PHPLIB-235: Document exception classes and interfaces

docs/reference.txt

@@ -6,9 +6,10 @@ Reference
 
 .. toctree::
    :titlesonly:
-   
+
    /reference/bson
    /reference/class/MongoDBClient
    /reference/class/MongoDBDatabase
    /reference/class/MongoDBCollection
    /reference/class/MongoDBGridFSBucket
+   /reference/exception-classes

docs/reference/exception-classes.txt

+=================
+Exception Classes
+=================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+MongoDB\\Exception\\BadMethodCallException
+------------------------------------------
+
+.. phpclass:: MongoDB\\Exception\\BadMethodCallException
+
+   This exception is thrown when an unsupported method is invoked on an object.
+
+   For example, using an unacknowledged write concern with
+   :phpmethod:`MongoDB\\Collection::insertMany()` will return a
+   :phpclass:`MongoDB\\InsertManyResult` object. It is a logical error to call
+   :phpmethod:`MongoDB\\InsertManyResult::getInsertedCount()`, since the number
+   of inserted documents can only be determined from the response of an
+   acknowledged write operation.
+
+   This class extends PHP's :php:`BadMethodCallException
+   <badmethodcallexception>` class and implements the library's
+   :phpclass:`Exception <MongoDB\\Exception\\Exception>` interface.
+
+----
+
+MongoDB\\Exception\\InvalidArgumentException
+--------------------------------------------
+
+.. phpclass:: MongoDB\\Exception\\InvalidArgumentException
+
+   Thrown for errors related to the parsing of parameters or options within the
+   library.
+
+   This class extends the driver's :php:`InvalidArgumentException
+   <mongodb-driver-exception-invalidargumentexception>` class and implements the
+   library's :phpclass:`Exception <MongoDB\\Exception\\Exception>` interface.
+
+----
+
+MongoDB\\Exception\\UnexpectedValueException
+--------------------------------------------
+
+.. phpclass:: MongoDB\\Exception\\UnexpectedValueException
+
+   This exception is thrown when a command response from the server is
+   malformed or not what the library expected. This exception means that an
+   assertion in some operation, which abstracts a database command, has failed.
+   It may indicate a corrupted BSON response or bug in the server, driver, or
+   library.
+
+   This class extends the driver's :php:`UnexpectedValueException
+   <mongodb-driver-exception-unexpectedvalueexception>` class and implements the
+   library's :phpclass:`Exception <MongoDB\\Exception\\Exception>` interface.
+
+----
+
+MongoDB\\Exception\\UnsupportedException
+----------------------------------------
+
+.. phpclass:: MongoDB\\Exception\\UnsupportedException
+
+   This exception is thrown if an option is used and not supported by the
+   selected server. It is used sparingly in cases where silently ignoring the
+   unsupported option might otherwise lead to unexpected behavior.
+
+   For example, the ``collation`` option for
+   :phpmethod:`MongoDB\\Collection::deleteOne()` is only supported by
+   MongoDB 3.4+. Since collation determines how a document is matched, silently
+   ignoring the option for an older server version could result in an
+   unintended document being deleted.
+
+   This class extends the library's :phpclass:`RuntimeException
+   <MongoDB\\Exception\\RuntimeException>` class and implements the
+   library's :phpclass:`Exception <MongoDB\\Exception\\Exception>` interface.
+
+   .. note::
+
+      Unlike :phpclass:`InvalidArgumentException
+      <MongoDB\\Exception\\InvalidArgumentException>`, which may be thrown when
+      an operation's parameters and options are parsed during construction, the
+      selected server is not known until an operation is executed.
+
+----
+
+MongoDB\\Exception\\Exception
+-----------------------------
+
+.. phpclass:: MongoDB\\Exception\\Exception
+
+   This interface extends the driver's :php:`Exception
+   <mongodb-driver-exception-exception>` interface and is implemented by all
+   exception classes within the library.
+
+----
+
+MongoDB\\Exception\\RuntimeException
+------------------------------------
+
+.. phpclass:: MongoDB\\Exception\\RuntimeException
+
+   This class extends the driver's :php:`RuntimeException
+   <mongodb-driver-exception-runtimeexception>` class, which in turn extends
+   PHP's :php:`RuntimeException <runtimeexception>` class.