diff --git a/internals/zendapi/macros/ZEND_STRL.xml b/internals/zendapi/macros/ZEND_STRL.xml
index 210c5fed9f..05a86d68dd 100644
--- a/internals/zendapi/macros/ZEND_STRL.xml
+++ b/internals/zendapi/macros/ZEND_STRL.xml
@@ -1,21 +1,38 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.4 $ -->
+<!-- $Revision: 1.5 $ -->
 <refentry id="zend-macro.zend-strl">
  <refnamediv>
   <refname>ZEND_STRL</refname>
-  <refpurpose>...</refpurpose>
+  <refpurpose>Pass string pointer and length in one operation</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
   &reftitle.description;      
   <literallayout>#include &lt;zend.h&gt;</literallayout>
   <methodsynopsis>
-   <type>???</type><methodname>ZEND_STRL</methodname>
-    <methodparam><type>???</type><parameter>str</parameter></methodparam>
+   <void/><methodname>ZEND_STRL</methodname>
+    <methodparam><type>char *</type><parameter>str</parameter></methodparam>
   </methodsynopsis>
   <para>
-   ...
+   This is a convenience macro that can be used when passing a static string
+   to a  function that requires a string length argument together with a string.
+   This saves duplicating the static string in the sourcecode or adding an extra
+   variable for it.
   </para>
+  <example>
+   <title><function>ZEND_STRL</function> example</title>
+   <programlisting>
+<![CDATA[
+
+write(0, ZEND_STRL("Hello World!"));
+/* same as 
+char str[] = "Hello World!";
+write(0, str, sizeof(str)-1);  
+*/
+
+]]>
+   </programlisting>
+  </example>
  </refsect1>
 
  <refsect1 role="parameters">
@@ -26,7 +43,7 @@
      <term><parameter>str</parameter></term>
      <listitem>
       <para>
-       ...
+       Pointer to a zero terminated string.       
       </para>
      </listitem>
     </varlistentry>
@@ -34,13 +51,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_STRS.xml b/internals/zendapi/macros/ZEND_STRS.xml
index 5af65271d0..fa646774cd 100644
--- a/internals/zendapi/macros/ZEND_STRS.xml
+++ b/internals/zendapi/macros/ZEND_STRS.xml
@@ -1,20 +1,23 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.4 $ -->
+<!-- $Revision: 1.5 $ -->
 <refentry id="zend-macro.zend-strs">
  <refnamediv>
   <refname>ZEND_STRS</refname>
-  <refpurpose>...</refpurpose>
+  <refpurpose>Pass string pointer and buffer size in one operation</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
   &reftitle.description;      
   <literallayout>#include &lt;zend.h&gt;</literallayout>
   <methodsynopsis>
-   <type>???</type><methodname>ZEND_STRS</methodname>
-    <methodparam><type>???</type><parameter>str</parameter></methodparam>
+   <void/><methodname>ZEND_STRS</methodname>
+    <methodparam><type>char *</type><parameter>str</parameter></methodparam>
   </methodsynopsis>
   <para>
-   ...
+   This is a convenience macro that can be used when passing a static string
+   to a  function that requires a buffer length argument together with a string.
+   This saves duplicating the static string in the sourcecode or adding an extra
+   variable for it.
   </para>
  </refsect1>
 
diff --git a/internals/zendapi/macros/ZEND_TRUTH.xml b/internals/zendapi/macros/ZEND_TRUTH.xml
index 91b371786b..9104e3b16f 100644
--- a/internals/zendapi/macros/ZEND_TRUTH.xml
+++ b/internals/zendapi/macros/ZEND_TRUTH.xml
@@ -1,9 +1,9 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.5 $ -->
+<!-- $Revision: 1.6 $ -->
 <refentry id="zend-macro.zend-truth">
  <refnamediv>
   <refname>ZEND_TRUTH</refname>
-  <refpurpose>...</refpurpose>
+  <refpurpose>Cast a value to <type>zend_bool</type></refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
@@ -14,7 +14,7 @@
     <methodparam><type>mixed</type><parameter>x</parameter></methodparam>
   </methodsynopsis>
   <para>
-   ...
+   A simple conversion macro, actually defined as <literal>((x) ? 1 : 0)</literal>
   </para>
  </refsect1>
 
@@ -26,7 +26,7 @@
      <term><parameter>x</parameter></term>
      <listitem>
       <para>
-       ...
+       Value to cast
       </para>
      </listitem>
     </varlistentry>
@@ -37,7 +37,7 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   ...
+   1 if <parameter>x</parameter> was considered &true;, else 0
   </para>
  </refsect1>