[mongodb] Document duplicate keys behavior in BSON documents

reference/mongodb/bson/document/fromjson.xml

@@ -39,6 +39,7 @@
   <simpara>
    Returns a new <classname>MongoDB\BSON\Document</classname> instance.
   </simpara>
+  &mongodb.note.duplicate-keys.fromjson;
  </refsect1>
 
  <refsect1 role="errors">

reference/mongodb/bson/document/get.xml

@@ -42,6 +42,12 @@
     <classname>MongoDB\BSON\Int64</classname> instance.
    </simpara>
   </note>
+  <note>
+   <simpara>
+    If the document contains duplicate keys, the value of the first matching key
+    is returned.
+   </simpara>
+  </note>
  </refsect1>
 
  <refsect1 role="errors">

reference/mongodb/bson/document/getiterator.xml

@@ -26,6 +26,12 @@
    Returns a <classname>MongoDB\BSON\Iterator</classname> instance that can be
    used to iterate over all keys in the document.
   </simpara>
+  <note>
+   <simpara>
+    If the document contains duplicate keys, the iterator returns every
+    element in the original order.
+   </simpara>
+  </note>
  </refsect1>
 
  <refsect1 role="errors">

reference/mongodb/bson/document/offsetget.xml

@@ -42,6 +42,12 @@
     <classname>MongoDB\BSON\Int64</classname> instance.
    </simpara>
   </note>
+  <note>
+   <simpara>
+    If the document contains duplicate keys, the value of the first matching key
+    is returned.
+   </simpara>
+  </note>
  </refsect1>
 
  <refsect1 role="errors">

reference/mongodb/bson/document/tocanonicalextendedjson.xml

@@ -35,6 +35,7 @@
    <link xlink:href="&url.mongodb.specs.extendedjson;#canonical-extended-json-example">Canonical Extended JSON</link>
    representation of the BSON document.
   </simpara>
+  &mongodb.note.duplicate-keys.tojson;
  </refsect1>
 
  <refsect1 role="examples">

reference/mongodb/bson/document/torelaxedextendedjson.xml

@@ -34,6 +34,7 @@
    <link xlink:href="&url.mongodb.specs.extendedjson;#relaxed-extended-json-example">Relaxed Extended JSON</link>
    representation of the BSON document.
   </simpara>
+  &mongodb.note.duplicate-keys.tojson;
  </refsect1>
 
  <refsect1 role="examples">

reference/mongodb/entities.mongodb.ent

@@ -752,6 +752,23 @@ local: {
    </note>
 </entity>
 
+<entity name="mongodb.note.duplicate-keys.tojson">
+  <note>
+   <simpara>
+    If the BSON document contains duplicate keys, all of them are preserved in
+    the JSON output.
+   </simpara>
+  </note>
+</entity>
+
+<entity name="mongodb.note.duplicate-keys.fromjson">
+  <note>
+   <simpara>
+    Duplicate keys in the JSON string are preserved in the order they appear.
+   </simpara>
+  </note>
+</entity>
+
 <entity name="mongodb.note.extended-json">
   <note>
    <simpara>
@@ -816,10 +833,10 @@ local: {
    <warning>
     <simpara>
      BSON documents can technically contain duplicate keys because documents are
-     stored as a list of key-value pairs; however, applications should refrain
-     from generating documents with duplicate keys as server and driver behavior
-     may be undefined. Since PHP objects and arrays cannot have duplicate keys,
-     data could also be lost when decoding a BSON document with duplicate keys.
+     stored as a list of key-value pairs; however, applications should avoid
+     creating documents with duplicate keys. The server and other drivers may
+     handle them differently, and PHP objects and arrays cannot have duplicate
+     keys, so data is lost when decoding a BSON document with duplicate keys.
     </simpara>
    </warning>
 </entity>

reference/mongodb/functions/bson/fromjson.xml

@@ -49,6 +49,7 @@
   <simpara>
    The serialized BSON document as a binary string.
   </simpara>
+  &mongodb.note.duplicate-keys.fromjson;
  </refsect1>
 
  <refsect1 role="errors">

reference/mongodb/functions/bson/tocanonicalextendedjson.xml

@@ -53,6 +53,7 @@
   <simpara>
    The converted JSON value.
   </simpara>
+  &mongodb.note.duplicate-keys.tojson;
  </refsect1>
 
  <refsect1 role="errors">

reference/mongodb/functions/bson/tojson.xml

@@ -78,6 +78,7 @@
   <simpara>
    The converted JSON value.
   </simpara>
+  &mongodb.note.duplicate-keys.tojson;
  </refsect1>
 
  <refsect1 role="errors">

reference/mongodb/functions/bson/torelaxedextendedjson.xml

@@ -52,6 +52,7 @@
   <simpara>
    The converted JSON value.
   </simpara>
+  &mongodb.note.duplicate-keys.tojson;
  </refsect1>
 
  <refsect1 role="errors">