From 105769eb557af47e5f2d0bea47457827114942fa Mon Sep 17 00:00:00 2001
From: Christoph Michael Becker <cmb@php.net>
Date: Sun, 22 Nov 2020 22:50:38 +0000
Subject: [PATCH] Generate sysvsem methodsynopses based on stubs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Based on a patch contributed by Máté Kocsis <kocsismate@woohoolabs.com>.


git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@351507 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/sem/functions/sem-acquire.xml | 18 +++++------
 reference/sem/functions/sem-get.xml     | 43 +++++++++++++++++++++----
 reference/sem/functions/sem-release.xml | 34 ++++++++++++++++---
 reference/sem/functions/sem-remove.xml  | 34 ++++++++++++++++---
 4 files changed, 104 insertions(+), 25 deletions(-)

diff --git a/reference/sem/functions/sem-acquire.xml b/reference/sem/functions/sem-acquire.xml
index d2b6fe95d3..ed6c2b62ca 100644
--- a/reference/sem/functions/sem-acquire.xml
+++ b/reference/sem/functions/sem-acquire.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.sem-acquire">
+<refentry xml:id="function.sem-acquire" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
   <refname>sem_acquire</refname>
   <refpurpose>Acquire a semaphore</refpurpose>
@@ -10,8 +10,8 @@
   &reftitle.description;
   <methodsynopsis>
    <type>bool</type><methodname>sem_acquire</methodname>
-   <methodparam><type>resource</type><parameter>sem_identifier</parameter></methodparam>
-   <methodparam choice="opt"><type>bool</type><parameter>nowait</parameter><initializer>&false;</initializer></methodparam>
+   <methodparam><type>SysvSemaphore</type><parameter>semaphore</parameter></methodparam>
+   <methodparam choice="opt"><type>bool</type><parameter>non_blocking</parameter><initializer>&false;</initializer></methodparam>
   </methodsynopsis>
   <para>
    <function>sem_acquire</function> by default blocks (if necessary) until the
@@ -31,16 +31,16 @@
   <para>
    <variablelist>
     <varlistentry>
-     <term><parameter>sem_identifier</parameter></term>
+     <term><parameter>semaphore</parameter></term>
      <listitem>
       <para>
-       <parameter>sem_identifier</parameter> is a semaphore resource,
+       <parameter>semaphore</parameter> is a semaphore
        obtained from <function>sem_get</function>.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
-     <term><parameter>nowait</parameter></term>
+     <term><parameter>non_blocking</parameter></term>
      <listitem>
       <para>
        Specifies if the process shouldn't wait for the semaphore to be acquired.
@@ -74,9 +74,10 @@
      </thead>
      <tbody>
       <row>
-       <entry>5.6.1</entry>
+       <entry>8.0.0</entry>
        <entry>
-        The <parameter>$nowait</parameter> parameter was added.
+        <parameter>semaphore</parameter> expects a <classname>SysvSemaphore</classname>
+        instance now; previously, a <type>resource</type> was expected.
        </entry>
       </row>
      </tbody>
@@ -96,7 +97,6 @@
  </refsect1>  
  
 </refentry>
-
 <!-- Keep this comment at the end of the file
 Local variables:
 mode: sgml
diff --git a/reference/sem/functions/sem-get.xml b/reference/sem/functions/sem-get.xml
index 81b9bf616b..0bd3015371 100644
--- a/reference/sem/functions/sem-get.xml
+++ b/reference/sem/functions/sem-get.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.sem-get">
+<refentry xml:id="function.sem-get" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
   <refname>sem_get</refname>
   <refpurpose>Get a semaphore id</refpurpose>
@@ -9,11 +9,11 @@
  <refsect1 role="description">
   &reftitle.description;
   <methodsynopsis>
-   <type>resource</type><methodname>sem_get</methodname>
+   <type class="union"><type>SysvSemaphore</type><type>false</type></type><methodname>sem_get</methodname>
    <methodparam><type>int</type><parameter>key</parameter></methodparam>
    <methodparam choice="opt"><type>int</type><parameter>max_acquire</parameter><initializer>1</initializer></methodparam>
-   <methodparam choice="opt"><type>int</type><parameter>perm</parameter><initializer>0666</initializer></methodparam>
-   <methodparam choice="opt"><type>int</type><parameter>auto_release</parameter><initializer>1</initializer></methodparam>
+   <methodparam choice="opt"><type>int</type><parameter>permissions</parameter><initializer>0666</initializer></methodparam>
+   <methodparam choice="opt"><type>bool</type><parameter>auto_release</parameter><initializer>&true;</initializer></methodparam>
   </methodsynopsis>
   <para>
    <function>sem_get</function> returns an id that can be used to
@@ -51,7 +51,7 @@
      </listitem>
     </varlistentry>
     <varlistentry>
-     <term><parameter>perm</parameter></term>
+     <term><parameter>permissions</parameter></term>
      <listitem>
       <para>
        The semaphore permissions. Actually this value is
@@ -81,6 +81,38 @@
   </para>
  </refsect1>
 
+ <refsect1 role="changelog">
+  &reftitle.changelog;
+  <para>
+   <informaltable>
+    <tgroup cols="2">
+     <thead>
+      <row>
+       <entry>&Version;</entry>
+       <entry>&Description;</entry>
+      </row>
+     </thead>
+     <tbody>
+      <row>
+       <entry>8.0.0</entry>
+       <entry>
+        On success, this function returns a <classname>SysvSemaphore</classname> instance now;
+        previously, a <type>resource</type> was returned.
+       </entry>
+      </row>
+      <row>
+       <entry>8.0.0</entry>
+       <entry>
+        The type of <parameter>auto_release</parameter> has been changed from
+        <type>int</type> to <type>bool</type>.
+       </entry>
+      </row>
+     </tbody>
+    </tgroup>
+   </informaltable>
+  </para>
+ </refsect1>
+ 
  <refsect1 role="notes">
   &reftitle.notes;
   <warning>
@@ -106,7 +138,6 @@
  </refsect1>  
 
 </refentry>
-
 <!-- Keep this comment at the end of the file
 Local variables:
 mode: sgml
diff --git a/reference/sem/functions/sem-release.xml b/reference/sem/functions/sem-release.xml
index 6abbbf6dcd..c1a904c780 100644
--- a/reference/sem/functions/sem-release.xml
+++ b/reference/sem/functions/sem-release.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.sem-release">
+<refentry xml:id="function.sem-release" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
   <refname>sem_release</refname>
   <refpurpose>Release a semaphore</refpurpose>
@@ -10,7 +10,7 @@
   &reftitle.description;
   <methodsynopsis>
    <type>bool</type><methodname>sem_release</methodname>
-   <methodparam><type>resource</type><parameter>sem_identifier</parameter></methodparam>
+   <methodparam><type>SysvSemaphore</type><parameter>semaphore</parameter></methodparam>
   </methodsynopsis>
   <para>
    <function>sem_release</function> releases the semaphore if it
@@ -28,10 +28,10 @@
   <para>
    <variablelist>
     <varlistentry>
-     <term><parameter>sem_identifier</parameter></term>
+     <term><parameter>semaphore</parameter></term>
      <listitem>
       <para>
-       A Semaphore resource handle as returned by
+       A Semaphore as returned by
        <function>sem_get</function>.
       </para>
      </listitem>
@@ -47,6 +47,31 @@
   </para>
  </refsect1>
 
+ <refsect1 role="changelog">
+  &reftitle.changelog;
+  <para>
+   <informaltable>
+    <tgroup cols="2">
+     <thead>
+      <row>
+       <entry>&Version;</entry>
+       <entry>&Description;</entry>
+      </row>
+     </thead>
+     <tbody>
+      <row>
+       <entry>8.0.0</entry>
+       <entry>
+        <parameter>semaphore</parameter> expects a <classname>SysvSemaphore</classname>
+        instance now; previously, a <type>resource</type> was expected.
+       </entry>
+      </row>
+     </tbody>
+    </tgroup>
+   </informaltable>
+  </para>
+ </refsect1>
+ 
  <refsect1 role="seealso">
   &reftitle.seealso;
   <para>
@@ -58,7 +83,6 @@
  </refsect1>  
 
 </refentry>
-
 <!-- Keep this comment at the end of the file
 Local variables:
 mode: sgml
diff --git a/reference/sem/functions/sem-remove.xml b/reference/sem/functions/sem-remove.xml
index 9d9f2ed8da..98ef3b8ff6 100644
--- a/reference/sem/functions/sem-remove.xml
+++ b/reference/sem/functions/sem-remove.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.sem-remove">
+<refentry xml:id="function.sem-remove" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
   <refname>sem_remove</refname>
   <refpurpose>Remove a semaphore</refpurpose>
@@ -10,7 +10,7 @@
   &reftitle.description;
   <methodsynopsis>
    <type>bool</type><methodname>sem_remove</methodname>
-   <methodparam><type>resource</type><parameter>sem_identifier</parameter></methodparam>
+   <methodparam><type>SysvSemaphore</type><parameter>semaphore</parameter></methodparam>
   </methodsynopsis>
   <para>
    <function>sem_remove</function> removes the given semaphore.
@@ -25,10 +25,10 @@
   <para>
    <variablelist>
     <varlistentry>
-     <term><parameter>sem_identifier</parameter></term>
+     <term><parameter>semaphore</parameter></term>
      <listitem>
       <para>
-       A semaphore resource identifier as returned
+       A semaphore as returned
        by <function>sem_get</function>.
       </para>
      </listitem>
@@ -44,6 +44,31 @@
   </para>
  </refsect1>
 
+ <refsect1 role="changelog">
+  &reftitle.changelog;
+  <para>
+   <informaltable>
+    <tgroup cols="2">
+     <thead>
+      <row>
+       <entry>&Version;</entry>
+       <entry>&Description;</entry>
+      </row>
+     </thead>
+     <tbody>
+      <row>
+       <entry>8.0.0</entry>
+       <entry>
+        <parameter>semaphore</parameter> expects a <classname>SysvSemaphore</classname>
+        instance now; previously, a <type>resource</type> was expected.
+       </entry>
+      </row>
+     </tbody>
+    </tgroup>
+   </informaltable>
+  </para>
+ </refsect1>
+ 
  <refsect1 role="seealso">
   &reftitle.seealso;
   <para>
@@ -56,7 +81,6 @@
  </refsect1>  
 
 </refentry>
-
 <!-- Keep this comment at the end of the file
 Local variables:
 mode: sgml