Sync some methodsynopses with stubs (#3356)

Co-authored-by: Gina Peter Banyard <girgias@php.net>
2026-03-23 23:32:18 +01:00 · 2024-04-28 22:42:56 +02:00
parent d4b0e5ea18
commit db22a7cfcb
17 changed files with 66 additions and 29 deletions
--- a/reference/fileinfo/functions/finfo-set-flags.xml
+++ b/reference/fileinfo/functions/finfo-set-flags.xml
@@ -11,7 +11,7 @@
  &reftitle.description;
  <para>&style.procedural;</para>
  <methodsynopsis>
-   <type>bool</type><methodname>finfo_set_flags</methodname>
+   <type>true</type><methodname>finfo_set_flags</methodname>
   <methodparam><type>finfo</type><parameter>finfo</parameter></methodparam>
   <methodparam><type>int</type><parameter>flags</parameter></methodparam>
  </methodsynopsis>
@@ -52,7 +52,7 @@
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
-   &return.success;
+   &return.true.always;
  </para>
 </refsect1>

--- a/reference/hash/functions/hash-file.xml
+++ b/reference/hash/functions/hash-file.xml
@@ -50,7 +50,8 @@
     <term><parameter>options</parameter></term>
     <listitem>
      <para>
-       An array of options for the various hashing algorithms.  Currently, only the "seed" parameter is
+       An array of options for the various hashing algorithms.
+       Currently, only the <literal>"seed"</literal> parameter is
       supported by the MurmurHash variants.
      </para>
     </listitem>
--- a/reference/hash/functions/hash-init.xml
+++ b/reference/hash/functions/hash-init.xml
@@ -53,7 +53,8 @@
     <term><parameter>options</parameter></term>
     <listitem>
      <para>
-       An array of options for the various hashing algorithms.  Currently, only the "seed" parameter is
+       An array of options for the various hashing algorithms.
+       Currently, only the <literal>"seed"</literal> parameter is
       supported by the MurmurHash variants.
      </para>
     </listitem>
--- a/reference/hash/functions/hash-pbkdf2.xml
+++ b/reference/hash/functions/hash-pbkdf2.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="function.hash-pbkdf2">
+<refentry xml:id="function.hash-pbkdf2" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>hash_pbkdf2</refname>
  <refpurpose>Generate a PBKDF2 key derivation of a supplied password</refpurpose>
@@ -16,6 +16,7 @@
   <methodparam><type>int</type><parameter>iterations</parameter></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>length</parameter><initializer>0</initializer></methodparam>
   <methodparam choice="opt"><type>bool</type><parameter>binary</parameter><initializer>&false;</initializer></methodparam>
+   <methodparam choice="opt"><type>array</type><parameter>options</parameter><initializer>[]</initializer></methodparam>
  </methodsynopsis>
 </refsect1>

@@ -82,6 +83,16 @@
      </para>
     </listitem>
    </varlistentry>
+    <varlistentry>
+     <term><parameter>options</parameter></term>
+     <listitem>
+      <para>
+       An array of options for the various hashing algorithms.
+       Currently, only the <literal>"seed"</literal> key is
+       supported by the MurmurHash variants.
+      </para>
+     </listitem>
+    </varlistentry>
   </variablelist>
  </para>
 </refsect1>
--- a/reference/hash/functions/hash-update.xml
+++ b/reference/hash/functions/hash-update.xml
@@ -8,7 +8,7 @@
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
-   <type>bool</type><methodname>hash_update</methodname>
+   <type>true</type><methodname>hash_update</methodname>
   <methodparam><type>HashContext</type><parameter>context</parameter></methodparam>
   <methodparam><type>string</type><parameter>data</parameter></methodparam>
  </methodsynopsis>
@@ -41,7 +41,7 @@
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
-   Returns &true;.
+   &return.true.always;
  </para>
 </refsect1>

@@ -82,7 +82,6 @@
 </refsect1>

 </refentry>
-
 <!-- Keep this comment at the end of the file
 Local variables:
 mode: sgml
--- a/reference/hash/functions/hash.xml
+++ b/reference/hash/functions/hash.xml
@@ -49,7 +49,8 @@
     <term><parameter>options</parameter></term>
     <listitem>
      <para>
-       An array of options for the various hashing algorithms.  Currently, only the "seed" parameter is
+       An array of options for the various hashing algorithms.
+       Currently, only the <literal>"seed"</literal> parameter is
       supported by the MurmurHash variants.
      </para>
     </listitem>
--- a/reference/ldap/functions/ldap-exop-sync.xml
+++ b/reference/ldap/functions/ldap-exop-sync.xml
@@ -11,8 +11,8 @@
   <type class="union"><type>LDAP\Result</type><type>bool</type></type><methodname>ldap_exop_sync</methodname>
   <methodparam><type>LDAP\Connection</type><parameter>ldap</parameter></methodparam>
   <methodparam><type>string</type><parameter>request_oid</parameter></methodparam>
-   <methodparam choice="opt"><type>string</type><parameter>request_data</parameter><initializer>&null;</initializer></methodparam>
-   <methodparam choice="opt"><type>array</type><parameter>controls</parameter><initializer>&null;</initializer></methodparam>
+   <methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>request_data</parameter><initializer>&null;</initializer></methodparam>
+   <methodparam choice="opt"><type class="union"><type>array</type><type>null</type></type><parameter>controls</parameter><initializer>&null;</initializer></methodparam>
   <methodparam choice="opt"><type>string</type><parameter role="reference">response_data</parameter><initializer>&null;</initializer></methodparam>
   <methodparam choice="opt"><type>string</type><parameter role="reference">response_oid</parameter><initializer>&null;</initializer></methodparam>
  </methodsynopsis>
--- a/reference/mbstring/functions/mb-get-info.xml
+++ b/reference/mbstring/functions/mb-get-info.xml
@@ -9,7 +9,7 @@
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
-   <type class="union"><type>array</type><type>string</type><type>int</type><type>false</type></type><methodname>mb_get_info</methodname>
+   <type class="union"><type>array</type><type>string</type><type>int</type><type>false</type><type>null</type></type><methodname>mb_get_info</methodname>
   <methodparam choice="opt"><type>string</type><parameter>type</parameter><initializer>"all"</initializer></methodparam>
  </methodsynopsis>
  <simpara>
--- a/reference/network/functions/openlog.xml
+++ b/reference/network/functions/openlog.xml
@@ -9,7 +9,7 @@
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
-   <type>bool</type><methodname>openlog</methodname>
+   <type>true</type><methodname>openlog</methodname>
   <methodparam><type>string</type><parameter>prefix</parameter></methodparam>
   <methodparam><type>int</type><parameter>flags</parameter></methodparam>
   <methodparam><type>int</type><parameter>facility</parameter></methodparam>
@@ -181,10 +181,32 @@
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
-   &return.success;
+   &return.true.always;
  </para>
 </refsect1>

+ <refsect1 role="changelog">
+  &reftitle.changelog;
+  <informaltable>
+   <tgroup cols="2">
+    <thead>
+     <row>
+      <entry>&Version;</entry>
+      <entry>&Description;</entry>
+     </row>
+    </thead>
+    <tbody>
+     <row>
+      <entry>8.2.0</entry>
+      <entry>
+       The function now always returns &true;. Previously it returned &false; on failure.
+      </entry>
+     </row>
+    </tbody>
+   </tgroup>
+  </informaltable>
+ </refsect1>
+
 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
--- a/reference/reflection/reflectionfiber/getexecutingfile.xml
+++ b/reference/reflection/reflectionfiber/getexecutingfile.xml
@@ -8,7 +8,7 @@
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis role="ReflectionFiber">
-   <modifier>public</modifier> <type>string</type><methodname>ReflectionFiber::getExecutingFile</methodname>
+   <modifier>public</modifier> <type class="union"><type>string</type><type>null</type></type><methodname>ReflectionFiber::getExecutingFile</methodname>
   <void/>
  </methodsynopsis>
  <para>
@@ -26,6 +26,7 @@
  &reftitle.returnvalues;
  <para>
   The full path and file name of the reflected fiber.
+   If the reflected fiber is used outside a user-defined function, &null; is returned.
  </para>
 </refsect1>

--- a/reference/reflection/reflectionfiber/getexecutingline.xml
+++ b/reference/reflection/reflectionfiber/getexecutingline.xml
@@ -8,12 +8,13 @@
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis role="ReflectionFiber">
-   <modifier>public</modifier> <type>int</type><methodname>ReflectionFiber::getExecutingLine</methodname>
+   <modifier>public</modifier> <type class="union"><type>int</type><type>null</type></type><methodname>ReflectionFiber::getExecutingLine</methodname>
   <void/>
  </methodsynopsis>
  <para>
-   Returns the line number of the current execution point in the reflected <classname>Fiber</classname>. If the fiber
-   has not been started or has terminated, an <classname>Error</classname> is thrown.
+   Returns the line number of the current execution point in the reflected <classname>Fiber</classname>.
+   If the reflected fiber is used outside a user-defined function, &null; is returned.
+   If the fiber has not been started or has terminated, an <classname>Error</classname> is thrown.
  </para>
 </refsect1>

--- a/reference/sockets/functions/socket-create-listen.xml
+++ b/reference/sockets/functions/socket-create-listen.xml
@@ -11,7 +11,7 @@
  <methodsynopsis>
   <type class="union"><type>Socket</type><type>false</type></type><methodname>socket_create_listen</methodname>
   <methodparam><type>int</type><parameter>port</parameter></methodparam>
-   <methodparam choice="opt"><type>int</type><parameter>backlog</parameter><initializer>128</initializer></methodparam>
+   <methodparam choice="opt"><type>int</type><parameter>backlog</parameter><initializer><constant>SOMAXCONN</constant></initializer></methodparam>
  </methodsynopsis>
  <para>
   <function>socket_create_listen</function> creates a new <classname>Socket</classname> instance of
--- a/reference/uodbc/functions/odbc-autocommit.xml
+++ b/reference/uodbc/functions/odbc-autocommit.xml
@@ -10,7 +10,7 @@
  <methodsynopsis>
   <type class="union"><type>int</type><type>bool</type></type><methodname>odbc_autocommit</methodname>
   <methodparam><type>resource</type><parameter>odbc</parameter></methodparam>
-   <methodparam choice="opt"><type>bool</type><parameter>enable</parameter><initializer>&null;</initializer></methodparam>
+   <methodparam choice="opt"><type class="union"><type>bool</type><type>null</type></type><parameter>enable</parameter><initializer>&null;</initializer></methodparam>
  </methodsynopsis>
  <para>
   Toggles autocommit behaviour.
@@ -47,13 +47,13 @@
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
-   Without the <parameter>enable</parameter> parameter, this function returns
+   With a &null; <parameter>enable</parameter> parameter, this function returns
   auto-commit status for <parameter>odbc</parameter>. Non-zero is
   returned if auto-commit is on, 0 if it is off, or &false; if an error
   occurs.
  </para>
  <para>
-   If <parameter>enable</parameter> is set, this function returns &true; on
+   If <parameter>enable</parameter> is non-null, this function returns &true; on
   success and &false; on failure.
  </para>
 </refsect1>
--- a/reference/uodbc/functions/odbc-binmode.xml
+++ b/reference/uodbc/functions/odbc-binmode.xml
@@ -8,7 +8,7 @@
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
-   <type>bool</type><methodname>odbc_binmode</methodname>
+   <type>true</type><methodname>odbc_binmode</methodname>
   <methodparam><type>resource</type><parameter>statement</parameter></methodparam>
   <methodparam><type>int</type><parameter>mode</parameter></methodparam>
  </methodsynopsis>
@@ -137,7 +137,7 @@
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
-   &return.success;
+   &return.true.always;
  </para>
 </refsect1>
 </refentry>
--- a/reference/uodbc/functions/odbc-data-source.xml
+++ b/reference/uodbc/functions/odbc-data-source.xml
@@ -8,7 +8,7 @@
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
-   <type class="union"><type>array</type><type>false</type></type><methodname>odbc_data_source</methodname>
+   <type class="union"><type>array</type><type>null</type><type>false</type></type><methodname>odbc_data_source</methodname>
   <methodparam><type>resource</type><parameter>odbc</parameter></methodparam>
   <methodparam><type>int</type><parameter>fetch_type</parameter></methodparam>
  </methodsynopsis>
--- a/reference/uodbc/functions/odbc-free-result.xml
+++ b/reference/uodbc/functions/odbc-free-result.xml
@@ -8,7 +8,7 @@
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
-   <type>bool</type><methodname>odbc_free_result</methodname>
+   <type>true</type><methodname>odbc_free_result</methodname>
   <methodparam><type>resource</type><parameter>statement</parameter></methodparam>
  </methodsynopsis>
  <para>
@@ -38,7 +38,7 @@
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
-   Always returns &true;.
+   &return.true.always;
  </para>
 </refsect1>
 <refsect1 role="notes">
--- a/reference/uodbc/functions/odbc-longreadlen.xml
+++ b/reference/uodbc/functions/odbc-longreadlen.xml
@@ -8,7 +8,7 @@
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
-   <type>bool</type><methodname>odbc_longreadlen</methodname>
+   <type>true</type><methodname>odbc_longreadlen</methodname>
   <methodparam><type>resource</type><parameter>statement</parameter></methodparam>
   <methodparam><type>int</type><parameter>length</parameter></methodparam>
  </methodsynopsis>
@@ -46,7 +46,7 @@
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
-   &return.success;
+   &return.true.always;
  </para>
 </refsect1>
 <refsect1 role="notes">