diff --git a/reference/array/functions/array-diff.xml b/reference/array/functions/array-diff.xml
index 4b691cf60c..ce5563efc8 100644
--- a/reference/array/functions/array-diff.xml
+++ b/reference/array/functions/array-diff.xml
@@ -58,6 +58,7 @@
   <para>
    Returns an <type>array</type> containing all the entries from
    <parameter>array1</parameter> that are not present in any of the other arrays.
+   Keys in the <parameter>array1</parameter> array are preserved.
   </para>
  </refsect1>
 
@@ -91,18 +92,54 @@ Array
     </screen>
    </example>
   </para>
+
+  <para>
+   <example>
+    <title><function>array_diff</function> example with non-matching types</title>
+    <para>
+     Two elements are considered equal if and only if
+     <literal>(string) $elem1 === (string) $elem2</literal>. That is,
+     when the <link linkend="language.types.string.casting">string representation</link> is the same.
+    </para>
+    <programlisting role="php">
+     <![CDATA[
+<?php
+// This will generate a Notice that an array cannot be cast to a string.
+$source = [1, 2, 3, 4];
+$filter = [3, 4, [5], 6];
+$result = array_diff($source, $filter);
+
+// Whereas this is fine, since the objects can cast to a string.
+class S {
+  private $v;
+
+  public function __construct(string $v) {
+    $this->v = $v;
+  }
+
+  public function __toString() {
+    return $this->v;
+  }
+}
+
+$source = [new S('a'), new S('b'), new S('c')];
+$filter = [new S('b'), new S('c'), new S('d')];
+
+$result = array_diff($source, $filter);
+
+// $result now contains one instance of S('a');
+?>
+]]>
+    </programlisting>
+    <para>
+     To use an alternate comparison function, see <function>array_udiff</function>.
+    </para>
+   </example>
+  </para>
  </refsect1>
 
  <refsect1 role="notes">
   &reftitle.notes;
-  <note>
-   <para>
-    Two elements are considered equal if and only if
-    <literal>(string) $elem1 === (string) $elem2</literal>. In other words:
-    when the string representation is the same.
-    <!-- TODO: example of it... -->
-   </para>
-  </note>
   <note>
    <para>
     This function only checks one dimension of a n-dimensional
@@ -117,6 +154,7 @@ Array
   <para>
    <simplelist>
     <member><function>array_diff_assoc</function></member>
+    <member><function>array_udiff</function></member>
     <member><function>array_intersect</function></member>
     <member><function>array_intersect_assoc</function></member>
    </simplelist>