diff --git a/internals/zendapi/macros/RETURN_BOOL.xml b/internals/zendapi/macros/RETURN_BOOL.xml
index e994ada97e..a045b65c68 100644
--- a/internals/zendapi/macros/RETURN_BOOL.xml
+++ b/internals/zendapi/macros/RETURN_BOOL.xml
@@ -1,9 +1,9 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.5 $ -->
+<!-- $Revision: 1.6 $ -->
 <refentry id="zend-macro.return-bool">
  <refnamediv>
   <refname>RETURN_BOOL</refname>
-  <refpurpose>...</refpurpose>
+  <refpurpose>Return a <type>bool</type> value from a function</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
@@ -14,7 +14,9 @@
     <methodparam><type>zend_bool</type><parameter>b</parameter></methodparam>
   </methodsynopsis>
   <para>
-   ...
+   <function>RETURN_BOOL</function> sets the <literal>return_value</literal>
+   of the given function to <parameter>b</parameter> and returns control to
+   the calling function.
   </para>
  </refsect1>
 
@@ -26,7 +28,7 @@
      <term><parameter>b</parameter></term>
      <listitem>
       <para>
-       ...
+       <type>bool</type> value to return.
       </para>
      </listitem>
     </varlistentry>
@@ -34,13 +36,6 @@
   </para>
  </refsect1>
 
- <refsect1 role="returnvalues">
-  &reftitle.returnvalues;
-  <para>
-   ...
-  </para>
- </refsect1>
-
 </refentry>
 
 <!-- Keep this comment at the end of the file
diff --git a/internals/zendapi/macros/RETURN_DOUBLE.xml b/internals/zendapi/macros/RETURN_DOUBLE.xml
index c76a58d3ac..3ad89e5b23 100644
--- a/internals/zendapi/macros/RETURN_DOUBLE.xml
+++ b/internals/zendapi/macros/RETURN_DOUBLE.xml
@@ -1,9 +1,9 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.5 $ -->
+<!-- $Revision: 1.6 $ -->
 <refentry id="zend-macro.return-double">
  <refnamediv>
   <refname>RETURN_DOUBLE</refname>
-  <refpurpose>...</refpurpose>
+  <refpurpose>Return a <type>double</type> value from a function</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
@@ -14,7 +14,9 @@
     <methodparam><type>double</type><parameter>d</parameter></methodparam>
   </methodsynopsis>
   <para>
-   ...
+   <function>RETURN_DOUBLE</function> sets the <literal>return_value</literal>
+   of the given function to <parameter>d</parameter> and returns control to
+   the calling function.
   </para>
  </refsect1>
 
@@ -26,7 +28,7 @@
      <term><parameter>d</parameter></term>
      <listitem>
       <para>
-       ...
+       <type>double</type> value to return.
       </para>
      </listitem>
     </varlistentry>
@@ -34,13 +36,6 @@
   </para>
  </refsect1>
 
- <refsect1 role="returnvalues">
-  &reftitle.returnvalues;
-  <para>
-   ...
-  </para>
- </refsect1>
-
 </refentry>
 
 <!-- Keep this comment at the end of the file
diff --git a/internals/zendapi/macros/RETURN_EMPTY_STRING.xml b/internals/zendapi/macros/RETURN_EMPTY_STRING.xml
index d7c81c41f5..3d2f463597 100644
--- a/internals/zendapi/macros/RETURN_EMPTY_STRING.xml
+++ b/internals/zendapi/macros/RETURN_EMPTY_STRING.xml
@@ -1,9 +1,9 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.5 $ -->
+<!-- $Revision: 1.6 $ -->
 <refentry id="zend-macro.return-empty-string">
  <refnamediv>
   <refname>RETURN_EMPTY_STRING</refname>
-  <refpurpose>...</refpurpose>
+  <refpurpose>Return an empty <type>string</type> value from a function</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
@@ -13,30 +13,7 @@
    <void/><methodname>RETURN_EMPTY_STRING</methodname><void/>
   </methodsynopsis>
   <para>
-   ...
-  </para>
- </refsect1>
-
- <refsect1 role="parameters">
-  &reftitle.parameters;
-  <para>
-   <variablelist>
-    <varlistentry>
-     <term><parameter></parameter></term>
-     <listitem>
-      <para>
-       ...
-      </para>
-     </listitem>
-    </varlistentry>
-   </variablelist>
-  </para>
- </refsect1>
-
- <refsect1 role="returnvalues">
-  &reftitle.returnvalues;
-  <para>
-   ...
+   This returns an empty string without the need to create such a string first.
   </para>
  </refsect1>
 
diff --git a/internals/zendapi/macros/RETURN_LONG.xml b/internals/zendapi/macros/RETURN_LONG.xml
index 0aabdca7df..250861ef42 100644
--- a/internals/zendapi/macros/RETURN_LONG.xml
+++ b/internals/zendapi/macros/RETURN_LONG.xml
@@ -1,9 +1,9 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.5 $ -->
+<!-- $Revision: 1.6 $ -->
 <refentry id="zend-macro.return-long">
  <refnamediv>
   <refname>RETURN_LONG</refname>
-  <refpurpose>...</refpurpose>
+  <refpurpose>Return a <type>long</type> value from a function</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
@@ -14,7 +14,9 @@
     <methodparam><type>long</type><parameter>l</parameter></methodparam>
   </methodsynopsis>
   <para>
-   ...
+   <function>RETURN_LONG</function> sets the <literal>return_value</literal>
+   of the given function to <parameter>l</parameter> and returns control to
+   the calling function.
   </para>
  </refsect1>
 
@@ -26,7 +28,7 @@
      <term><parameter>l</parameter></term>
      <listitem>
       <para>
-       ...
+       <type>long</type> value to return.
       </para>
      </listitem>
     </varlistentry>
@@ -34,13 +36,6 @@
   </para>
  </refsect1>
 
- <refsect1 role="returnvalues">
-  &reftitle.returnvalues;
-  <para>
-   ...
-  </para>
- </refsect1>
-
 </refentry>
 
 <!-- Keep this comment at the end of the file
diff --git a/internals/zendapi/macros/RETURN_NULL.xml b/internals/zendapi/macros/RETURN_NULL.xml
index f625544fed..984bbb352f 100644
--- a/internals/zendapi/macros/RETURN_NULL.xml
+++ b/internals/zendapi/macros/RETURN_NULL.xml
@@ -1,9 +1,9 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.5 $ -->
+<!-- $Revision: 1.6 $ -->
 <refentry id="zend-macro.return-null">
  <refnamediv>
   <refname>RETURN_NULL</refname>
-  <refpurpose>...</refpurpose>
+  <refpurpose>Return a <type>null</type> value from a function</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
@@ -13,30 +13,9 @@
    <void/><methodname>RETURN_NULL</methodname><void/>
   </methodsynopsis>
   <para>
-   ...
-  </para>
- </refsect1>
-
- <refsect1 role="parameters">
-  &reftitle.parameters;
-  <para>
-   <variablelist>
-    <varlistentry>
-     <term><parameter></parameter></term>
-     <listitem>
-      <para>
-       ...
-      </para>
-     </listitem>
-    </varlistentry>
-   </variablelist>
-  </para>
- </refsect1>
-
- <refsect1 role="returnvalues">
-  &reftitle.returnvalues;
-  <para>
-   ...
+   <function>RETURN_BOOL</function> sets the <literal>return_value</literal>
+   of the given function to &null; and returns control to
+   the calling function.
   </para>
  </refsect1>
 
diff --git a/internals/zendapi/macros/RETURN_RESOURCE.xml b/internals/zendapi/macros/RETURN_RESOURCE.xml
index c120cc686f..7990c83136 100644
--- a/internals/zendapi/macros/RETURN_RESOURCE.xml
+++ b/internals/zendapi/macros/RETURN_RESOURCE.xml
@@ -1,20 +1,22 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.4 $ -->
+<!-- $Revision: 1.5 $ -->
 <refentry id="zend-macro.return-resource">
  <refnamediv>
   <refname>RETURN_RESOURCE</refname>
-  <refpurpose>...</refpurpose>
+  <refpurpose>Return a <type>resource</type> from a function</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
   &reftitle.description;      
   <literallayout>#include &lt;zend_API.h&gt;</literallayout>
   <methodsynopsis>
-   <type>???</type><methodname>RETURN_RESOURCE</methodname>
-    <methodparam><type>???</type><parameter>l</parameter></methodparam>
+   <void><methodname>RETURN_RESOURCE</methodname>
+    <methodparam><type>resource</type><parameter>r</parameter></methodparam>
   </methodsynopsis>
   <para>
-   ...
+   <function>RETURN_RESOURCE</function> sets the <literal>return_value</literal>
+   of the given function to <parameter>r</parameter> and returns control to
+   the calling function.
   </para>
  </refsect1>
 
@@ -23,10 +25,10 @@
   <para>
    <variablelist>
     <varlistentry>
-     <term><parameter>l</parameter></term>
+     <term><parameter>r</parameter></term>
      <listitem>
       <para>
-       ...
+       The resource to be returned.
       </para>
      </listitem>
     </varlistentry>
@@ -34,13 +36,6 @@
   </para>
  </refsect1>
 
- <refsect1 role="returnvalues">
-  &reftitle.returnvalues;
-  <para>
-   ...
-  </para>
- </refsect1>
-
 </refentry>
 
 <!-- Keep this comment at the end of the file
diff --git a/internals/zendapi/macros/RETURN_ZVAL.xml b/internals/zendapi/macros/RETURN_ZVAL.xml
index f54678478e..8fd035525c 100644
--- a/internals/zendapi/macros/RETURN_ZVAL.xml
+++ b/internals/zendapi/macros/RETURN_ZVAL.xml
@@ -1,19 +1,19 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.4 $ -->
+<!-- $Revision: 1.5 $ -->
 <refentry id="zend-macro.return-zval">
  <refnamediv>
   <refname>RETURN_ZVAL</refname>
-  <refpurpose>...</refpurpose>
+  <refpurpose>Return a <type>zval</type> value from a function</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
   &reftitle.description;      
   <literallayout>#include &lt;zend_API.h&gt;</literallayout>
   <methodsynopsis>
-   <type>???</type><methodname>RETURN_ZVAL</methodname>
-    <methodparam><type>???</type><parameter>zv</parameter></methodparam>
-    <methodparam><type>???</type><parameter>copy</parameter></methodparam>
-    <methodparam><type>???</type><parameter>dtor</parameter></methodparam>
+   <void/><methodname>RETURN_ZVAL</methodname>
+    <methodparam><type>zval *</type><parameter>zv</parameter></methodparam>
+    <methodparam><type>bool</type><parameter>copy</parameter></methodparam>
+    <methodparam><type>bool</type><parameter>dtor</parameter></methodparam>
   </methodsynopsis>
   <para>
    ...
@@ -28,7 +28,7 @@
      <term><parameter>zv</parameter></term>
      <listitem>
       <para>
-       ...
+       Pointer to the <type>zval</type> to return.
       </para>
      </listitem>
     </varlistentry>
@@ -36,7 +36,7 @@
      <term><parameter>copy</parameter></term>
      <listitem>
       <para>
-       ...
+       Create a copy of <parameter>zv</parameter> before returning it?
       </para>
      </listitem>
     </varlistentry>
@@ -44,7 +44,9 @@
      <term><parameter>dtor</parameter></term>
      <listitem>
       <para>
-       ...
+       Destruct the original value before returning fromt he function,
+       this is needed if <parameter>zv</parameter> was only temporarily
+       created within the function.
       </para>
      </listitem>
     </varlistentry>
@@ -52,13 +54,6 @@
   </para>
  </refsect1>
 
- <refsect1 role="returnvalues">
-  &reftitle.returnvalues;
-  <para>
-   ...
-  </para>
- </refsect1>
-
 </refentry>
 
 <!-- Keep this comment at the end of the file
diff --git a/internals/zendapi/macros/ZEND_NUM_ARGS.xml b/internals/zendapi/macros/ZEND_NUM_ARGS.xml
index 0890cf397e..193afcba8a 100644
--- a/internals/zendapi/macros/ZEND_NUM_ARGS.xml
+++ b/internals/zendapi/macros/ZEND_NUM_ARGS.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.5 $ -->
+<!-- $Revision: 1.6 $ -->
 <refentry id="zend-macro.zend-num-args">
  <refnamediv>
   <refname>ZEND_NUM_ARGS</refname>
@@ -13,30 +13,15 @@
    <type>int</type><methodname>ZEND_NUM_ARGS</methodname><void/>
   </methodsynopsis>
   <para>
-   ...
-  </para>
- </refsect1>
-
- <refsect1 role="parameters">
-  &reftitle.parameters;
-  <para>
-   <variablelist>
-    <varlistentry>
-     <term><parameter></parameter></term>
-     <listitem>
-      <para>
-       ...
-      </para>
-     </listitem>
-    </varlistentry>
-   </variablelist>
+   <function>ZEND_NUM_ARGS</function> returns the number of arguments
+   that have been passed by the caller of the current PHP function.
   </para>
  </refsect1>
 
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   ...
+   Number of argunemts passed to the current PHP function.
   </para>
  </refsect1>