Add ChangeStream documentation (#439)

* Add ChangeStream documentation

Author: kvwalker

source/includes/apiargs-MongoDBCollection-method-watch-option.yaml

@@ -0,0 +1,49 @@
+source:
+  file: apiargs-MongoDBCollection-method-aggregate-option.yaml
+  ref: batchSize
+---
+source:
+  file: apiargs-MongoDBCollection-common-option.yaml
+  ref: collation
+---
+arg_name: option
+name: fullDocument
+type: string
+description: |
+  Allowed values are 'default' and 'updateLookup'. Defaults to 'default'.
+  When set to 'updateLookup', the change notification for partial updates will
+  include both a delta describing the changes to the document, as well as a
+  copy of the entire document that was changed from some time after the change
+  occurred. The following values are supported:
+
+  - ``MongoDB\Operation\ChangeStream::FULL_DOCUMENT_DEFAULT`` (*default*)
+  - ``MongoDB\Operation\ChangeStream::FULL_DOCUMENT_UPDATE_LOOKUP``
+interface: phpmethod
+operation: ~
+optional: true
+---
+source:
+  file: apiargs-MongoDBCollection-method-find-option.yaml
+  ref: maxAwaitTimeMS
+---
+arg_name: option
+name: readPreference
+type: :php:`MongoDB\\Driver\\ReadPreference <class.mongodb-driver-readpreference>`
+description: |
+  The read preference for the initial change stream aggregation, used for
+  server selection during an automatic resume.
+interface: phpmethod
+operation: ~
+optional: true
+---
+arg_name: option
+name: resumeAfter
+type: array|object
+description: |
+  Specifies the logical starting point for the new change stream.
+
+  Note this is an option of the '$changeStream' pipeline stage.
+interface: phpmethod
+operation: ~
+optional: true
+...

source/includes/apiargs-MongoDBCollection-method-watch-param.yaml

@@ -0,0 +1,13 @@
+arg_name: param
+name: $pipeline
+type: array|object
+description: |
+  The pipeline of stages to append to an initial ``$changeStream`` stage.
+interface: phpmethod
+operation: ~
+optional: true
+---
+source:
+  file: apiargs-common-param.yaml
+  ref: $options
+...

source/reference/class/MongoDBCollection.txt

@@ -91,4 +91,5 @@ Methods
    /reference/method/MongoDBCollection-replaceOne
    /reference/method/MongoDBCollection-updateMany
    /reference/method/MongoDBCollection-updateOne
+   /reference/method/MongoDBCollection-watch
    /reference/method/MongoDBCollection-withOptions

source/reference/method/MongoDBCollection-watch.txt

@@ -0,0 +1,52 @@
+================================
+MongoDB\\Collection::watch()
+================================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+Definition
+----------
+
+.. phpmethod:: MongoDB\\Collection::watch()
+
+   Executes a :manual:`change stream </changeStreams>` operation on the
+   collection.
+
+   .. code-block:: php
+
+      function watch(array $pipeline = [], array $options = []): MongoDB\ChangeStream
+
+   This method has the following parameters:
+
+   .. include:: /includes/apiargs/MongoDBCollection-method-watch-param.rst
+
+   The ``$options`` parameter supports the following options:
+
+   .. include:: /includes/apiargs/MongoDBCollection-method-watch-option.rst
+
+Return Values
+-------------
+
+A :phpclass:`MongoDB\\ChangeStream` object, which allows for iteration of
+events in the change stream via the :php:`Iterator <class.iterator>` interface.
+
+Errors/Exceptions
+-----------------
+
+.. include:: /includes/extracts/error-unexpectedvalueexception.rst
+.. include:: /includes/extracts/error-unsupportedexception.rst
+.. include:: /includes/extracts/error-invalidargumentexception.rst
+.. include:: /includes/extracts/error-driver-runtimeexception.rst
+
+See Also
+--------
+
+- :manual:`Aggregation Pipeline </core/aggregation-pipeline>` documentation in
+  the MongoDB Manual
+- :manual:`Change Streams </changeStreams>` documentation in the MongoDB manual