From a678daf64f4c44a1b822477edee14b6e8bae7e9e Mon Sep 17 00:00:00 2001
From: Jeremy Mikola <jmikola@gmail.com>
Date: Tue, 7 Jun 2022 18:51:34 -0400
Subject: [PATCH] Document comment and let options for BulkWrite and Query

https://jira.mongodb.org/browse/PHPC-2049
https://jira.mongodb.org/browse/PHPC-2005
---
 language-snippets.ent                         | 14 +++++++++++
 .../mongodb/driver/bulkwrite/construct.xml    | 23 +++++++++++++++++++
 .../mongodb/driver/query/construct.xml        | 20 +++++++++++++---
 3 files changed, 54 insertions(+), 3 deletions(-)

diff --git a/language-snippets.ent b/language-snippets.ent
index 274e1c4c1d..6f20a51ad3 100644
--- a/language-snippets.ent
+++ b/language-snippets.ent
@@ -2681,6 +2681,20 @@ used.</para>'>
           </entry>
          </row>
 '>
+<!ENTITY mongodb.option.let '
+         <row xmlns="http://docbook.org/ns/docbook">
+          <entry>let</entry>
+          <entry><type class="union"><type>array</type><type>object</type></type></entry>
+          <entry>
+           <para>
+            Map of parameter names and values. Values must be constant or closed expressions that do not reference document fields. Parameters can then be accessed as variables in an aggregate expression context (e.g. <literal>$$var</literal>).
+           </para>
+           <para>
+            This option is available in MongoDB 5.0+ and will result in an exception at execution time if specified for an older server version.
+           </para>
+          </entry>
+         </row>
+'>
 <!ENTITY mongodb.option.encryption.keyVaultClient '
          <row xmlns="http://docbook.org/ns/docbook">
           <entry>keyVaultClient</entry>
diff --git a/reference/mongodb/mongodb/driver/bulkwrite/construct.xml b/reference/mongodb/mongodb/driver/bulkwrite/construct.xml
index a6b866382f..cdf93ee08d 100644
--- a/reference/mongodb/mongodb/driver/bulkwrite/construct.xml
+++ b/reference/mongodb/mongodb/driver/bulkwrite/construct.xml
@@ -55,6 +55,22 @@
           </entry>
           <entry>&false;</entry>
          </row>
+         <row>
+          <entry>comment</entry>
+          <entry><type>mixed</type></entry>
+          <entry>
+           <para>
+            An arbitrary comment to help trace the operation through the
+            database profiler, currentOp output, and logs.
+           </para>
+           <para>
+            This option is available in MongoDB 4.4+ and will result in an
+            exception at execution time if specified for an older server
+            version.
+           </para>
+          </entry>
+         </row>
+         &mongodb.option.let;
          <row>
           <entry>ordered</entry>
           <entry><type>bool</type></entry>
@@ -93,6 +109,13 @@
       </row>
      </thead>
      <tbody>
+      <row>
+       <entry>PECL mongodb 1.14.0</entry>
+       <entry>
+        Added the <literal>"comment"</literal> and <literal>"let"</literal>
+        options.
+       </entry>
+      </row>
       <row>
        <entry>PECL mongodb 1.1.0</entry>
        <entry>
diff --git a/reference/mongodb/mongodb/driver/query/construct.xml b/reference/mongodb/mongodb/driver/query/construct.xml
index 8b289c3d58..94edeec60c 100644
--- a/reference/mongodb/mongodb/driver/query/construct.xml
+++ b/reference/mongodb/mongodb/driver/query/construct.xml
@@ -96,11 +96,15 @@
          &mongodb.option.collation;
          <row>
           <entry>comment</entry>
-          <entry><type>string</type></entry>
+          <entry><type>mixed</type></entry>
           <entry>
            <para>
-            A comment to attach to the query to help interpret and trace query
-            profile data.
+            An arbitrary comment to help trace the operation through the
+            database profiler, currentOp output, and logs.
+           </para>
+           <para>
+            The comment can be any valid BSON type for MongoDB 4.4+. Earlier
+            server versions only support string values.
            </para>
            <para>
             Falls back to the deprecated <literal>"$comment"</literal> modifier
@@ -163,6 +167,7 @@
            </para>
           </entry>
          </row>
+         &mongodb.option.let;
          <row>
           <entry>limit</entry>
           <entry><type>int</type></entry>
@@ -431,6 +436,15 @@
       </row>
      </thead>
      <tbody>
+      <row>
+       <entry>PECL mongodb 1.14.0</entry>
+       <entry>
+        <para>
+         Added the <literal>"let"</literal> option. The
+         <literal>"comment"</literal> option now accepts any type.
+        </para>
+       </entry>
+      </row>
       <row>
        <entry>PECL mongodb 1.8.0</entry>
        <entry>