PHPLIB-749: Support comment option on command helpers (#925)

Co-authored-by: Jeremy Mikola <[email protected]>

docs/includes/apiargs-MongoDBClient-method-dropDatabase-option.yaml

@@ -1,3 +1,12 @@
+source:
+  file: apiargs-common-option.yaml
+  ref: comment
+post: |
+  This is not supported for server versions prior to 4.4 and will result in an
+  exception at execution time if used.
+
+  .. versionadded:: 1.13
+---
 source:
   file: apiargs-common-option.yaml
   ref: session

docs/includes/apiargs-MongoDBClient-method-listDatabases-option.yaml

@@ -13,6 +13,15 @@ interface: phpmethod
 operation: ~
 optional: true
 ---
+source:
+  file: apiargs-common-option.yaml
+  ref: comment
+post: |
+  This is not supported for server versions prior to 4.4 and will result in an
+  exception at execution time if used.
+
+  .. versionadded:: 1.13
+---
 arg_name: option
 name: filter
 type: array|object

docs/includes/apiargs-MongoDBClient-method-watch-option.yaml

@@ -7,6 +7,15 @@ source:
   file: apiargs-common-option.yaml
   ref: collation
 ---
+source:
+  file: apiargs-common-option.yaml
+  ref: comment
+post: |
+  The comment can be any valid BSON type for server versions 4.4 and above.
+  Earlier server versions only support string values.
+
+  .. versionadded:: 1.13
+---
 source:
   file: apiargs-method-watch-option.yaml
   ref: fullDocument

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

@@ -11,9 +11,12 @@ source:
   ref: bypassDocumentValidation
 ---
 source:
-  file: apiargs-aggregate-option.yaml
+  file: apiargs-common-option.yaml
   ref: comment
 post: |
+  The comment can be any valid BSON type for server versions 4.4 and above.
+  Earlier server versions only support string values.
+
   .. versionadded:: 1.3
 ---
 source:

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

@@ -2,6 +2,15 @@ source:
   file: apiargs-MongoDBCollection-common-option.yaml
   ref: bypassDocumentValidation
 ---
+source:
+  file: apiargs-common-option.yaml
+  ref: comment
+post: |
+  This is not supported for server versions prior to 4.4 and will result in an
+  exception at execution time if used.
+
+  .. versionadded:: 1.13
+---
 source:
   file: apiargs-common-option.yaml
   ref: let

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

@@ -2,6 +2,15 @@ source:
   file: apiargs-MongoDBCollection-common-option.yaml
   ref: collation
 ---
+source:
+  file: apiargs-common-option.yaml
+  ref: comment
+post: |
+  This is not supported for server versions prior to 4.4 and will result in an
+  exception at execution time if used.
+
+  .. versionadded:: 1.13
+---
 arg_name: option
 name: hint
 type: string|array|object

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

@@ -2,6 +2,13 @@ source:
   file: apiargs-MongoDBCollection-common-option.yaml
   ref: collation
 ---
+source:
+  file: apiargs-common-option.yaml
+  ref: comment
+post: |
+  The comment can be any valid BSON type for server versions 4.4 and above.
+  Earlier server versions only support string values.
+---
 arg_name: option
 name: hint
 type: string|array|object

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

@@ -17,6 +17,15 @@ interface: phpmethod
 operation: ~
 optional: true
 ---
+source:
+  file: apiargs-common-option.yaml
+  ref: comment
+post: |
+  This is not supported for server versions prior to 4.4 and will result in an
+  exception at execution time if used.
+
+  .. versionadded:: 1.13
+---
 arg_name: option
 name: unique
 type: boolean

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

@@ -1,3 +1,12 @@
+source:
+  file: apiargs-common-option.yaml
+  ref: comment
+post: |
+  This is not supported for server versions prior to 4.4 and will result in an
+  exception at execution time if used.
+
+  .. versionadded:: 1.13
+---
 source:
   file: apiargs-MongoDBCollection-method-createIndex-option.yaml
   ref: commitQuorum

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

@@ -2,6 +2,15 @@ source:
   file: apiargs-MongoDBCollection-common-option.yaml
   ref: collation
 ---
+source:
+  file: apiargs-common-option.yaml
+  ref: comment
+post: |
+  This is not supported for server versions prior to 4.4 and will result in an
+  exception at execution time if used.
+
+  .. versionadded:: 1.13
+---
 source:
   file: apiargs-common-option.yaml
   ref: hint

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

@@ -2,6 +2,15 @@ source:
   file: apiargs-MongoDBCollection-common-option.yaml
   ref: collation
 ---
+source:
+  file: apiargs-common-option.yaml
+  ref: comment
+post: |
+  This is not supported for server versions prior to 4.4 and will result in an
+  exception at execution time if used.
+
+  .. versionadded:: 1.13
+---
 source:
   file: apiargs-common-option.yaml
   ref: hint

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

@@ -2,6 +2,15 @@ source:
   file: apiargs-MongoDBCollection-common-option.yaml
   ref: collation
 ---
+source:
+  file: apiargs-common-option.yaml
+  ref: comment
+post: |
+  This is not supported for server versions prior to 4.4 and will result in an
+  exception at execution time if used.
+
+  .. versionadded:: 1.13
+---
 source:
   file: apiargs-common-option.yaml
   ref: maxTimeMS

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

@@ -1,3 +1,12 @@
+source:
+  file: apiargs-common-option.yaml
+  ref: comment
+post: |
+  This is not supported for server versions prior to 4.4 and will result in an
+  exception at execution time if used.
+
+  .. versionadded:: 1.13
+---
 source:
   file: apiargs-dropCollection-option.yaml
   ref: encryptedFields

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

@@ -1,3 +1,12 @@
+source:
+  file: apiargs-common-option.yaml
+  ref: comment
+post: |
+  This is not supported for server versions prior to 4.4 and will result in an
+  exception at execution time if used.
+
+  .. versionadded:: 1.13
+---
 source:
   file: apiargs-common-option.yaml
   ref: maxTimeMS

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

@@ -1,3 +1,12 @@
+source:
+  file: apiargs-common-option.yaml
+  ref: comment
+post: |
+  This is not supported for server versions prior to 4.4 and will result in an
+  exception at execution time if used.
+
+  .. versionadded:: 1.13
+---
 source:
   file: apiargs-common-option.yaml
   ref: maxTimeMS

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

@@ -1,3 +1,12 @@
+source:
+  file: apiargs-common-option.yaml
+  ref: comment
+post: |
+  This is not supported for server versions prior to 4.4 and will result in an
+  exception at execution time if used.
+
+  .. versionadded:: 1.13
+---
 source:
   file: apiargs-common-option.yaml
   ref: maxTimeMS

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

@@ -1,3 +1,14 @@
+source:
+  file: apiargs-common-option.yaml
+  ref: comment
+post: |
+  Defaults to the ``comment`` of the explained operation (if any).
+
+  This is not supported for server versions prior to 4.4 and will result in an
+  exception at execution time if used.
+
+  .. versionadded:: 1.13
+---
 source:
   file: apiargs-MongoDBCollection-common-option.yaml
   ref: readPreference

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

@@ -74,15 +74,12 @@ source:
   file: apiargs-MongoDBCollection-common-option.yaml
   ref: collation
 ---
-arg_name: option
-name: comment
-type: string
-description: |
-  A comment to attach to the query to help interpret and trace query
-  :dbcommand:`profile` data.
-interface: phpmethod
-operation: ~
-optional: true
+source:
+  file: apiargs-common-option.yaml
+  ref: comment
+post: |
+  The comment can be any valid BSON type for server versions 4.4 and above.
+  Earlier server versions only support string values.
 ---
 arg_name: option
 name: cursorType

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

@@ -10,6 +10,15 @@ source:
   file: apiargs-MongoDBCollection-common-option.yaml
   ref: collation
 ---
+source:
+  file: apiargs-common-option.yaml
+  ref: comment
+post: |
+  This is not supported for server versions prior to 4.4 and will result in an
+  exception at execution time if used.
+
+  .. versionadded:: 1.13
+---
 source:
   file: apiargs-common-option.yaml
   ref: hint

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

@@ -10,6 +10,15 @@ source:
   file: apiargs-MongoDBCollection-common-option.yaml
   ref: collation
 ---
+source:
+  file: apiargs-common-option.yaml
+  ref: comment
+post: |
+  This is not supported for server versions prior to 4.4 and will result in an
+  exception at execution time if used.
+
+  .. versionadded:: 1.13
+---
 source:
   file: apiargs-common-option.yaml
   ref: hint

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

@@ -16,6 +16,15 @@ source:
   file: apiargs-MongoDBCollection-common-option.yaml
   ref: collation
 ---
+source:
+  file: apiargs-common-option.yaml
+  ref: comment
+post: |
+  This is not supported for server versions prior to 4.4 and will result in an
+  exception at execution time if used.
+
+  .. versionadded:: 1.13
+---
 source:
   file: apiargs-common-option.yaml
   ref: hint

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

@@ -2,6 +2,15 @@ source:
   file: apiargs-MongoDBCollection-common-option.yaml
   ref: bypassDocumentValidation
 ---
+source:
+  file: apiargs-common-option.yaml
+  ref: comment
+post: |
+  This is not supported for server versions prior to 4.4 and will result in an
+  exception at execution time if used.
+
+  .. versionadded:: 1.13
+---
 source:
   file: apiargs-MongoDBCollection-method-bulkWrite-option.yaml
   ref: ordered

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

@@ -2,6 +2,15 @@ source:
   file: apiargs-MongoDBCollection-common-option.yaml
   ref: bypassDocumentValidation
 ---
+source:
+  file: apiargs-common-option.yaml
+  ref: comment
+post: |
+  This is not supported for server versions prior to 4.4 and will result in an
+  exception at execution time if used.
+
+  .. versionadded:: 1.13
+---
 source:
   file: apiargs-common-option.yaml
   ref: session

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

@@ -1,3 +1,12 @@
+source:
+  file: apiargs-common-option.yaml
+  ref: comment
+post: |
+  This is not supported for server versions prior to 4.4 and will result in an
+  exception at execution time if used.
+
+  .. versionadded:: 1.13
+---
 source:
   file: apiargs-common-option.yaml
   ref: maxTimeMS

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

@@ -8,6 +8,15 @@ source:
   file: apiargs-MongoDBCollection-common-option.yaml
   ref: collation
 ---
+source:
+  file: apiargs-common-option.yaml
+  ref: comment
+post: |
+  This is not supported for server versions prior to 4.4 and will result in an
+  exception at execution time if used.
+
+  .. versionadded:: 1.13
+---
 arg_name: option
 name: finalize
 type: :php:`MongoDB\\BSON\\Javascript <class.mongodb-bson-javascript>`

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

@@ -1,3 +1,12 @@
+source:
+  file: apiargs-common-option.yaml
+  ref: comment
+post: |
+  This is not supported for server versions prior to 4.4 and will result in an
+  exception at execution time if used.
+
+  .. versionadded:: 1.13
+---
 source:
   file: apiargs-MongoDBCollection-common-option.yaml
   ref: typeMap