diff --git a/functions/mysql.xml b/functions/mysql.xml
index 391c83cea5..4325ef3498 100644
--- a/functions/mysql.xml
+++ b/functions/mysql.xml
@@ -1217,14 +1217,39 @@ mysql_close();
       </paramdef>
      </funcprototype>
     </funcsynopsis>
-    <para> 
+    <para>
      <function>mysql_insert_id</function> returns the ID generated for
-     an AUTO_INCREMENT field.  It will return the auto-generated ID
-     returned by the last INSERT query performed using the given
-     <parameter>link_identifier</parameter>.  If
+     an AUTO_INCREMENT column by the previous INSERT query using the
+     given <parameter>link_identifier</parameter>.  If
      <parameter>link_identifier</parameter> isn't specified, the last
      opened link is assumed.
     </para>
+    <para>
+     <function>mysql_insert_id</function> returns 0 if the previous
+     query does not generate an AUTO_INCREMENT value. If you need to
+     save the value for later, be sure to call mysql_insert_id()
+     immediately after the query that generates the value.
+    </para>
+    <note>
+     <para>
+      The value of the MySQL SQL function
+      <literal>LAST_INSERT_ID()</literal> always contains the most
+      recently generated AUTO_INCREMENT value, and is not reset
+      between queries.
+    </para>
+    </note>
+    <warning>
+     <para>
+      <function>mysql_insert_id</function> converts the return type of
+      the native MySQL C API function
+      <literal>mysql_insert_id()</literal> to a type of
+      <literal>long</literal>.  If your AUTO_INCREMENT column has
+      a column type of BIGINT, the value returned by
+      <function>mysql_insert_id</function> will be incorrect.
+      Instead, use the internal MySQL SQL function
+      <literal>LAST_INSERT_ID()</literal>.
+     </para>
+    </warning>
    </refsect1>
   </refentry>