diff --git a/reference/mysql/functions/mysql-free-result.xml b/reference/mysql/functions/mysql-free-result.xml
index c4077f1c5f..2d93758ab1 100644
--- a/reference/mysql/functions/mysql-free-result.xml
+++ b/reference/mysql/functions/mysql-free-result.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
 <!-- splitted from ./en/functions/mysql.xml, last change in rev 1.102 -->
   <refentry id="function.mysql-free-result">
    <refnamediv>
@@ -21,15 +21,49 @@
      you are concerned about how much memory is being used for queries
      that return large result sets.  All associated result memory is
      automatically freed at the end of the script's execution.
-     <!-- TODO and as of PHP 4 before, see freeing resources -->
     </para>
     <para>
      &return.success;
     </para>
+    <para>
+     If a non-resource is used for the <parameter>result</parameter>, an
+     error of level E_WARNING will be emitted.  It's worth noting that
+     <function>mysql_query</function> only returns a <type>resource</type>
+     for SELECT, SHOW, EXPLAIN, and DESCRIBE queries.
+    </para>
+    <para>
+     <example>
+      <title>A <function>mysql_free_result</function> example</title>
+      <programlisting role="php">
+<![CDATA[
+<?php
+$result = mysql_query("SELECT id,email FROM people WHERE id = '42'");
+if (!$result) {
+    echo 'Could not run query: ' . mysql_error();
+    exit;
+}
+/* Use the result, assuming we're done with it afterwords */
+$row = mysql_fetch_assoc($result);
+
+/* Now we free up the result and continue on with our script */
+mysql_free_result($result);
+
+echo $row['id'];
+echo $row['email'];
+
+?>
+]]>
+      </programlisting>
+     </example>
+    </para>
     <para>
      For downward compatibility <function>mysql_freeresult</function>
      can also be used. This is deprecated, however.
     </para>
+    <para>
+     See also <function>mysql_query</function> and 
+     <function>is_resource</function>.
+    </para>
    </refsect1>
   </refentry>