docs(python): Clarify behavior of DataFrame.rows_by_key

py-polars/polars/dataframe/frame.py

@@ -9580,6 +9580,10 @@ def rows(
         """
         Returns all data in the DataFrame as a list of rows of python-native values.
 
+        By default, each row is returned as a tuple of values given in the same order
+        as the frame columns. Setting `named=True` will return rows of dictionaries
+        instead.
+
         Parameters
         ----------
         named
@@ -9598,12 +9602,13 @@ def rows(
         --------
         Row-iteration is not optimal as the underlying data is stored in columnar form;
         where possible, prefer export via one of the dedicated export/output methods.
-        Where possible you should also consider using `iter_rows` instead to avoid
-        materialising all the data at once.
+        You should also consider using `iter_rows` instead, to avoid materialising all
+        the data at once; there is little performance difference between the two, but
+        peak memory can be reduced if processing rows in batches.
 
         Returns
         -------
-        list of tuples (default) or dictionaries of row values
+        list of row value tuples (default), or list of dictionaries (if `named=True`).
 
         See Also
         --------
@@ -9643,7 +9648,10 @@ def rows_by_key(
         unique: bool = False,
     ) -> dict[Any, Iterable[Any]]:
         """
-        Returns DataFrame data as a keyed dictionary of python-native values.
+        Returns all data as a dictionary of python-native values keyed by some column.
+
+        This method is like `rows`, but instead of returning rows in a flat list, rows
+        are grouped by the values in the `key` column(s) and returned as a dictionary.
 
         Note that this method should not be used in place of native operations, due to
         the high cost of materializing all frame data out into a dictionary; it should