PHPLIB-364: Deprecate count() and elaborate on count method behaviors

docs/reference/method/MongoDBCollection-count.txt

@@ -2,6 +2,8 @@
 MongoDB\\Collection::count()
 ============================
 
+.. deprecated:: 1.4
+
 .. default-domain:: mongodb
 
 .. contents:: On this page
@@ -45,12 +47,24 @@ Errors/Exceptions
 Behavior
 --------
 
-.. include:: /includes/extracts/note-bson-comparison.rst
+This method is deprecated and cannot be executed within a transaction. It has
+always been implemented using the :manual:`count </reference/command/count>`
+command. The behavior of the ``count`` command differs depending on the options
+passed to it and may or may not provide an accurate count. When no query filter
+is provided, the ``count`` command provides an estimate using collection
+metadata. Even when provided with a query filter the ``count`` command can
+return inaccurate results with a sharded cluster if orphaned documents exist or
+if a chunk migration is in progress. The
+:phpmethod:`MongoDB\\Collection::countDocuments()` method avoids these sharded
+cluster problems entirely when used with MongoDB 3.6+, and when a primary read
+preference with older sharded clusters.
 
-.. todo: add output and examples
+.. include:: /includes/extracts/note-bson-comparison.rst
 
 See Also
 --------
 
 - :manual:`count </reference/command/count>` command reference in the MongoDB
   manual
+- :phpmethod:`MongoDB\\Collection::countDocuments()`
+- :phpmethod:`MongoDB\\Collection::estimatedDocumentCount()`

docs/reference/method/MongoDBCollection-countDocuments.txt

@@ -47,8 +47,6 @@ Errors/Exceptions
 Behavior
 --------
 
-.. include:: /includes/extracts/note-bson-comparison.rst
-
 Internally, this method uses the ``$group`` aggregation pipeline operator to
 obtain the result. If a ``filter`` parameter is given, this is converted into
 a ``$match`` pipeline operator. Optional ``$skip`` and ``$limit`` stages are
@@ -73,4 +71,11 @@ Consider the following alternatives to these restricted operators:
    * - :query:`$where`
      - :query:`$expr` (requires MongoDB 3.6+)
 
+.. include:: /includes/extracts/note-bson-comparison.rst
+
 .. todo: add output and examples
+
+See Also
+--------
+
+- :phpmethod:`MongoDB\\Collection::estimatedDocumentCount()`

docs/reference/method/MongoDBCollection-estimatedDocumentCount.txt

@@ -47,10 +47,14 @@ Errors/Exceptions
 Behavior
 --------
 
-.. include:: /includes/extracts/note-bson-comparison.rst
+This method returns an estimate of the count of documents in the collection
+using collection metadata, rather than counting the documents or consulting an
+index. This method does not take a ``session`` option and cannot be executed
+within a transaction.
 
 See Also
 --------
 
 - :manual:`count </reference/command/count>` command reference in the MongoDB
   manual
+- :phpmethod:`MongoDB\\Collection::countDocuments()`