Clarification of return values descriptions for mysqli fetch functions (#841)

Co-authored-by: shevchenko.r <r.shevchenko@bookcentre.ru>
Co-authored-by: Kamil Tekiela <tekiela246@gmail.com>

reference/mysqli/mysqli_result/fetch-array.xml

@@ -29,14 +29,14 @@
    this function can also store the data in associative indices 
    by using the field names of the result set as keys.
   </para>
-  &database.field-case;
-  &database.fetch-null;
   <para>
-   If two or more columns of the result have the same field names, the last
-   column will take precedence and overwrite the earlier data. In order to
+   If two or more columns of the result have the same name, the last
+   column will take precedence and overwrite any previous data. To
    access multiple columns with the same name, the numerically indexed
    version of the row must be used.
   </para>
+  &database.field-case;
+  &database.fetch-null;
  </refsect1>
 
  <refsect1 role="parameters">

reference/mysqli/mysqli_result/fetch-assoc.xml

@@ -23,6 +23,14 @@
    Returns an associative array that corresponds to the fetched row or &null;
    if there are no more rows.
   </para>
+  <para>
+   If two or more columns of the result have the same name, the last
+   column will take precedence and overwrite any previous data. To
+   access multiple columns with the same name,
+   <function>mysqli_fetch_row</function> may be used to fetch the numerically
+   indexed array, or aliases may be used in the SQL query select list to give
+   columns different names.
+  </para>
   &database.field-case;
   &database.fetch-null;
  </refsect1>
@@ -39,16 +47,10 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   Returns an associative array of values representing the fetched row in the result
+   Returns an associative array representing the fetched row in the result
    set, where each key in the array represents the name of one of the result
    set's columns or &null; if there are no more rows in result set.
   </para>
-  <para>
-   If two or more columns of the result have the same field names, the last
-   column will take precedence. To access the other column(s) of the same
-   name, you either need to access the result with numeric indices by using
-   <function>mysqli_fetch_row</function> or add alias names.
-  </para>
  </refsect1>
 
  <refsect1 role="examples">
@@ -105,7 +107,7 @@ Santa Clara (USA)
   <example xml:id="mysqli-result.example.iterator">
    <title>Comparison of <classname>mysqli_result</classname> <classname>iterator</classname> and <methodname>mysqli_result::fetch_assoc</methodname> usage</title>
    <para>
-    <classname>mysqli_result</classname> can be iterated using &foreach;. 
+    <classname>mysqli_result</classname> can be iterated using &foreach;.
     The result set will always be iterated from the first row, regardless of the current position.
    </para>
    <programlisting role="php">

reference/mysqli/mysqli_result/fetch-object.xml

@@ -27,6 +27,14 @@
    result set as an object where the attributes of the object represent the
    names of the fields found within the result set.
   </para>
+  <para>
+   If two or more columns of the result have the same name, the last
+   column will take precedence and overwrite any previous data. To
+   access multiple columns with the same name,
+   <function>mysqli_fetch_row</function> may be used to fetch the numerically
+   indexed array, or aliases may be used in the SQL query select list to give
+   columns different names.
+  </para>
   <note xmlns="http://docbook.org/ns/docbook">
    <simpara>
      This function sets the properties
@@ -67,8 +75,9 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   Returns an object that corresponds to the fetched
-   row or &null; if there are no more rows in result set.
+   Returns an object representing the fetched row, where each property
+   represents the name of the result set's column, or &null;
+   if there are no more rows in the result set.
   </para>
  </refsect1>
 

reference/mysqli/mysqli_result/fetch-row.xml

@@ -40,7 +40,7 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   <function>mysqli_fetch_row</function> returns an array of values that corresponds to the fetched row
+   <function>mysqli_fetch_row</function> returns an enumerated array representing the fetched row
    or &null; if there are no more rows in result set.
   </para>
  </refsect1>