Improve the documentation of mysqli_stmt_result_metadata()

php/doc-en@8abf640

Author: mumumu

reference/mysqli/mysqli_stmt/result-metadata.xml

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: 63b99082ef83eade08151f8cb528246fded81db9 Maintainer: takagi Status: ready -->
+<!-- EN-Revision: 8abf6408d9259abbd5c5bfb5077ce841db7f5735 Maintainer: takagi Status: ready -->
 <!-- Credits: mumumu -->
 <refentry xml:id="mysqli-stmt.result-metadata" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
@@ -23,14 +23,24 @@
   </methodsynopsis>
   <para>
    <function>mysqli_prepare</function> に渡したステートメントが
-   結果セットを返すものであった場合、<function>mysqli_stmt_result_metadata</function>
+   結果セットを返すものであった場合、
+   <function>mysqli_stmt_result_metadata</function>
    はオブジェクトを返します。このオブジェクトは、結果のフィールド数や
    各フィールドの情報などのメタ情報を取得するために使用可能です。
   </para>
+  <simpara>
+   この関数は空の <classname>mysqli_result</classname> オブジェクトを返します。
+   これにより、実際のデータ行を取得せずに、
+   プリペアドステートメントからメタデータ情報にアクセスできます。
+   <function>mysqli_stmt_get_result</function> を使用して、
+   プリペアドステートメントから結果オブジェクトとして結果セット全体を取得する場合、
+   この関数を使用する必要はありません。
+  </simpara>
   <note>
    <para>
-    メタデータを取得するには、この結果セットポインタを、以下のいずれかの
-    (フィールドベースの) 関数に渡します。
+    この結果セットは、
+    結果セットのメタデータをフィールドベースで処理する関数にのみ渡せます。
+    渡せる関数の例として、以下が挙げられます:
     <itemizedlist>
      <listitem><para><function>mysqli_num_fields</function></para></listitem>
      <listitem><para><function>mysqli_fetch_field</function></para></listitem>
@@ -43,17 +53,14 @@
     </itemizedlist>
    </para>
   </note>
-  <para>
-   結果セットは、使用終了後に開放すべきです。そのためには、結果セットを
-   <function>mysqli_free_result</function> に渡します。
-  </para>
   <note>
-   <para>
+   <simpara>
     <function>mysqli_stmt_result_metadata</function> が返す結果セットには
-    メタデータのみが含まれています。実際の行データは含まれません。行データを
-    取得するには、ステートメントハンドルを <function>mysqli_stmt_fetch</function>
-    に渡してください。
-   </para>
+    メタデータのみが含まれています。実際の行データは含まれません。
+    行データを取得するには、ステートメントハンドルを
+    <function>mysqli_stmt_get_result</function> または、
+    <function>mysqli_stmt_fetch</function> に渡してください。
+   </simpara>
   </note>
  </refsect1>
 
@@ -102,12 +109,6 @@ $result = $stmt->result_metadata();
 $field = $result->fetch_field();
 
 printf("Fieldname: %s\n", $field->name);
-
-/* 結果セットを閉じます */
-$result->close();
-
-/* 接続を閉じます */
-$mysqli->close();
 ?>
 ]]>
    </programlisting>
@@ -134,12 +135,6 @@ $result = mysqli_stmt_result_metadata($stmt);
 $field = mysqli_fetch_field($result);
 
 printf("Fieldname: %s\n", $field->name);
-
-/* 結果セットを閉じます */
-mysqli_free_result($result);
-
-/* 接続を閉じます */
-mysqli_close($link);
 ?>
 ]]>
    </programlisting>
@@ -152,6 +147,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>