Update documentation for ldap_search() (#1629)

* Update documentation for ldap_search()

* Improve documentation for ldap_search()

* Use new entity for return values, update additional ldap_* method docs

* Avoid text duplication in ldap documentation

* Move para tag into entity

Co-authored-by: Sergey Panteleev <sergey@php.net>

language-snippets.ent

@@ -1180,6 +1180,14 @@ Passing untrusted data to this parameter is <emphasis>insecure</emphasis>, unles
 </row>'>
 
 <!ENTITY ldap.return-result 'Returns an <classname xmlns="http://docbook.org/ns/docbook">LDAP\Result</classname> instance,&return.falseforfailure;.'>
+<!ENTITY ldap.return-result-array 'Returns an <classname xmlns="http://docbook.org/ns/docbook">LDAP\Result</classname> instance, an array of <classname xmlns="http://docbook.org/ns/docbook">LDAP\Result</classname> instances,&return.falseforfailure;.'>
+
+<!ENTITY ldap.return-result-array-info '<para xmlns="http://docbook.org/ns/docbook">It is also possible to perform parallel searches. In this case, the first argument should be an array of
+<classname>LDAP\Connection</classname> instances, rather than a single one.
+If the searches should not all use the same base DN and filter, an array of base DNs and/or an array of filters can be passed as arguments instead.
+These arrays must be of the same size as the <classname>LDAP\Connection</classname> instances array,
+since the first entries of the arrays are used for one search, the second entries are used for another, and so on.
+When doing parallel searches an array of <classname>LDAP\Result</classname> instances is returned, except in case of error, when the return value will be &false;.</para>'>
 
 <!-- mbstring notes -->
 

reference/ldap/functions/ldap-list.xml

@@ -31,6 +31,7 @@
    (Equivalent to typing "<command>ls</command>" and getting a list of files and folders in the
    current working directory.)
   </para>
+   &ldap.return-result-array-info;
  </refsect1>
 
  <refsect1 role="parameters">
@@ -173,7 +174,7 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   &ldap.return-result;
+   &ldap.return-result-array;
   </para>
  </refsect1>
 

reference/ldap/functions/ldap-read.xml

@@ -25,6 +25,7 @@
    directory with the scope <constant>LDAP_SCOPE_BASE</constant>. So it is
    equivalent to reading an entry from the directory.
   </para>
+   &ldap.return-result-array-info;
  </refsect1>
 
  <refsect1 role="parameters">
@@ -172,7 +173,7 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   &ldap.return-result;
+   &ldap.return-result-array;
   </para>
  </refsect1>
 

reference/ldap/functions/ldap-search.xml

@@ -25,22 +25,7 @@
    of <constant>LDAP_SCOPE_SUBTREE</constant>. This is equivalent to searching
    the entire directory.
   </para>
-  <para>
-   From 4.0.5 on it's also possible to do parallel searches. To do this
-   you use an array of link identifiers, rather than a single identifier,
-   as the first argument. If you don't want the same base DN and the
-   same filter for all the searches, you can also use an array of base DNs
-   and/or an array of filters. Those arrays must be of the same size as
-   the link identifier array since the first entries of the arrays are
-   used for one search, the second entries are used for another, and so
-   on. When doing parallel searches an array of search result
-   identifiers is returned, except in case of error, then the entry
-   corresponding to the search will be &false;. This is very much like
-   the value normally returned, except that a result identifier is always
-   returned when a search was made. There are some rare cases where the
-   normal search returns &false; while the parallel search returns an
-   identifier.
-  </para>
+   &ldap.return-result-array-info;
  </refsect1>
 
  <refsect1 role="parameters">
@@ -187,7 +172,7 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   &ldap.return-result;
+   &ldap.return-result-array;
   </para>
  </refsect1>