Improve the documentation of mysqli_stmt_result_metadata() (#4912)

Co-authored-by: Gina Peter Banyard <girgias@php.net>

Author: kamil-tekiela

reference/mysqli/mysqli_stmt/result-metadata.xml

@@ -25,8 +25,16 @@
    that can be used to process the meta information such as total number of fields
    and individual field information.
   </para>
+  <simpara>
+   This function returns an empty <classname>mysqli_result</classname> object
+   which can be used to access metadata information from the prepared statement
+   without having to fetch the actual rows of data. There is no need to use
+   this function when using <function>mysqli_stmt_get_result</function> to
+   retrieve the entire result set from a prepared statement as a result object.
+  </simpara>
   <note>
-   <para>This result set pointer can be passed as an argument to any of the
+   <para>
+    This result set object can be passed as an argument only to the
     field-based functions that process result set metadata, such as:
     <itemizedlist>
      <listitem><para><function>mysqli_num_fields</function></para></listitem>
@@ -40,16 +48,13 @@
     </itemizedlist>
    </para>
   </note>
-  <para>
-   The result set structure should be freed when you are done with it,
-   which you can do by passing it to <function>mysqli_free_result</function>
-  </para>
   <note>
-   <para>
-    The result set returned by <function>mysqli_stmt_result_metadata</function> contains only
-    metadata. It does not contain any row results. The rows are obtained by using the
-    statement handle with <function>mysqli_stmt_fetch</function>.
-   </para>
+   <simpara>
+    The result set returned by <function>mysqli_stmt_result_metadata</function>
+    contains only metadata. It does not contain any row results.
+    The rows are obtained by calling <function>mysqli_stmt_get_result</function>
+    on the statement handle or with <function>mysqli_stmt_fetch</function>.
+   </simpara>
   </note>
  </refsect1>
 
@@ -64,9 +69,10 @@
 
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
-  <para>
+  <simpara>
    Returns a result object or &false; if an error occurred.
-  </para>
+   If the statement does not produce a result set, &false; is returned as well.
+  </simpara>
  </refsect1>
 
  <refsect1 role="errors">
@@ -98,12 +104,6 @@ $result = $stmt->result_metadata();
 $field = $result->fetch_field();
 
 printf("Fieldname: %s\n", $field->name);
-
-/* close resultset */
-$result->close();
-
-/* close connection */
-$mysqli->close();
 ?>
 ]]>
    </programlisting>
@@ -130,12 +130,6 @@ $result = mysqli_stmt_result_metadata($stmt);
 $field = mysqli_fetch_field($result);
 
 printf("Fieldname: %s\n", $field->name);
-
-/* close resultset */
-mysqli_free_result($result);
-
-/* close connection */
-mysqli_close($link);
 ?>
 ]]>
    </programlisting>
@@ -148,6 +142,7 @@ mysqli_close($link);
    <simplelist>
     <member><function>mysqli_prepare</function></member>
     <member><function>mysqli_free_result</function></member>
+    <member><function>mysqli_stmt_get_result</function></member>
    </simplelist>
   </para>
  </refsect1>