From 09f638433b0084b0419c31e6a2a2ec2c5669a2ed Mon Sep 17 00:00:00 2001
From: Hartmut Holzgraefe <hholzgra@php.net>
Date: Sun, 22 Jan 2006 14:57:49 +0000
Subject: [PATCH] finished ZEND_MOD_REQUIRED*.xml, can be used as examples for
 the other ZEND_MOD_* macros

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@205706 c90b9560-bf6c-de11-be94-00142212c4b1
---
 .../zendapi/macros/ZEND_MOD_REQUIRED.xml      | 31 +++++++++++----
 .../zendapi/macros/ZEND_MOD_REQUIRED_EX.xml   | 38 +++++++++++++++----
 2 files changed, 55 insertions(+), 14 deletions(-)

diff --git a/internals/zendapi/macros/ZEND_MOD_REQUIRED.xml b/internals/zendapi/macros/ZEND_MOD_REQUIRED.xml
index 5ec07e2b81..a61a89eddc 100644
--- a/internals/zendapi/macros/ZEND_MOD_REQUIRED.xml
+++ b/internals/zendapi/macros/ZEND_MOD_REQUIRED.xml
@@ -1,9 +1,9 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.5 $ -->
+<!-- $Revision: 1.6 $ -->
 <refentry id="zend-macro.zend-mod-required">
  <refnamediv>
   <refname>ZEND_MOD_REQUIRED</refname>
-  <refpurpose>...</refpurpose>
+  <refpurpose>Create a simple dependency entry for a required extension</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
@@ -11,10 +11,14 @@
   <literallayout>#include &lt;zend_modules.h&gt;</literallayout>
   <methodsynopsis>
    <void/><methodname>ZEND_MOD_REQUIRED</methodname>
-    <methodparam><type>char *</type><parameter>name</parameter></methodparam>
+    <methodparam><type>char *</type><parameter>ext_name</parameter></methodparam>
   </methodsynopsis>
   <para>
-   ...
+   <function>ZEND_MOD_REQUIRED</function> generates a <type>zend_module_dep</type>
+   entry for the extension named by <parameter>ext_name</parameter>. A simple entry
+   without further version specifications is generated. 
+   See <function>ZEND_MOD_REQUIRED_EX</function> for an extended version of this
+   macro that also allows to specify version dependencies.
   </para>
  </refsect1>
 
@@ -23,10 +27,10 @@
   <para>
    <variablelist>
     <varlistentry>
-     <term><parameter>name</parameter></term>
+     <term><parameter>ext_name</parameter></term>
      <listitem>
       <para>
-       ...
+       The name of a reqiured extension
       </para>
      </listitem>
     </varlistentry>
@@ -37,10 +41,23 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   ...
+   Code to register the required extension dependency
   </para>
  </refsect1>
 
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <para>
+   See <function>ZEND_MOD_REQUIRED_EX</function> if you also need to 
+   specify extension version requirements.
+  </para>
+  <para>
+   See also <function>ZEND_MOD_OPTIONAL</function>,
+   <function>ZEND_MOD_OPTIONAL_EX</function>,
+   <function>ZEND_MOD_CONFLICTS</function>, and
+   <function>ZEND_MOD_CONFLICTS_EX</function>.
+  </para>
+ </refsect1>
 </refentry>
 
 <!-- Keep this comment at the end of the file
diff --git a/internals/zendapi/macros/ZEND_MOD_REQUIRED_EX.xml b/internals/zendapi/macros/ZEND_MOD_REQUIRED_EX.xml
index 149693e483..5eee041fd5 100644
--- a/internals/zendapi/macros/ZEND_MOD_REQUIRED_EX.xml
+++ b/internals/zendapi/macros/ZEND_MOD_REQUIRED_EX.xml
@@ -1,9 +1,9 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.5 $ -->
+<!-- $Revision: 1.6 $ -->
 <refentry id="zend-macro.zend-mod-required-ex">
  <refnamediv>
   <refname>ZEND_MOD_REQUIRED_EX</refname>
-  <refpurpose>...</refpurpose>
+  <refpurpose>Create a full dependency entry for the required version of an extension</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
@@ -16,8 +16,18 @@
     <methodparam><type>char *</type><parameter>ver</parameter></methodparam>
   </methodsynopsis>
   <para>
-   ...
+   <function>ZEND_MOD_REQUIRED_EX</function> generates a <type>zend_module_dep</type>
+   entry for the extension named by <parameter>ext_name</parameter>, including version
+   information. It allows to specify requirements like "up to version x.y", 
+   "starting with version x.y" or "exactly version x.y".
   </para>
+  <warning>
+   <para>
+    Version specific comparisons are not implemented yet, 
+    so for now <function>ZEND_MOD_REUQUIRE</function> and
+    <function>ZEND_MOD_REQUIRE_EX</function> define identical behavior.
+   </para>
+  </warning>
  </refsect1>
 
  <refsect1 role="parameters">
@@ -28,7 +38,7 @@
      <term><parameter>name</parameter></term>
      <listitem>
       <para>
-       ...
+       Name of the required extension
       </para>
      </listitem>
     </varlistentry>
@@ -36,7 +46,8 @@
      <term><parameter>rel</parameter></term>
      <listitem>
       <para>
-       ...
+       Comparison operator, one of <literal>eq</literal>, <literal>lt</literal>, 
+       <literal>le</literal>, <literal>gt</literal>, or <literal>ge</literal>
       </para>
      </listitem>
     </varlistentry>
@@ -44,7 +55,7 @@
      <term><parameter>ver</parameter></term>
      <listitem>
       <para>
-       ...
+       Version string
       </para>
      </listitem>
     </varlistentry>
@@ -55,10 +66,23 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   ...
+   Code to register the required extension
   </para>
  </refsect1>
 
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <para>
+   See <function>ZEND_MOD_REQUIRED</function> if you do not need to 
+   specify extension version requirements.
+  </para>
+  <para>
+   See also <function>ZEND_MOD_OPTIONAL</function>,
+   <function>ZEND_MOD_OPTIONAL_EX</function>,
+   <function>ZEND_MOD_CONFLICTS</function>, and
+   <function>ZEND_MOD_CONFLICTS_EX</function>.
+  </para>
+ </refsect1>
 </refentry>
 
 <!-- Keep this comment at the end of the file