From 62e8fe9bd23e00be74aa5d9076dd6250d5988920 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Severin=20Paul=20H=C3=B6fer?=
 <84280965+zzril@users.noreply.github.com>
Date: Thu, 13 Jul 2023 20:56:02 +0200
Subject: [PATCH] docs: Improve wording on stating that a method does not work
 in-place (#449)

Closes #346

### Summary of Changes

Updated the docstrings of methods in `src/safeds/data` to state that
copies are returned, with the original object left unmodified.

---------

Co-authored-by: Alexander <47296670+Marsmaennchen221@users.noreply.github.com>
Co-authored-by: megalinter-bot <129584137+megalinter-bot@users.noreply.github.com>
---
 src/safeds/data/image/containers/_image.py    | 63 +++++++++----
 src/safeds/data/tabular/containers/_column.py |  4 +-
 src/safeds/data/tabular/containers/_row.py    |  4 +-
 src/safeds/data/tabular/containers/_table.py  | 92 +++++++++----------
 .../data/tabular/containers/_tagged_table.py  | 82 ++++++++---------
 5 files changed, 137 insertions(+), 108 deletions(-)

diff --git a/src/safeds/data/image/containers/_image.py b/src/safeds/data/image/containers/_image.py
index a385c0a0c..6357d0527 100644
--- a/src/safeds/data/image/containers/_image.py
+++ b/src/safeds/data/image/containers/_image.py
@@ -207,7 +207,9 @@ def _repr_png_(self) -> bytes | None:
 
     def resize(self, new_width: int, new_height: int) -> Image:
         """
-        Return a new image that has been resized to a given size.
+        Return a new `Image` that has been resized to a given size.
+
+        The original image is not modified.
 
         Returns
         -------
@@ -220,7 +222,9 @@ def resize(self, new_width: int, new_height: int) -> Image:
 
     def convert_to_grayscale(self) -> Image:
         """
-        Convert the image to grayscale.
+        Return a new `Image` that is converted to grayscale.
+
+        The original image is not modified.
 
         Returns
         -------
@@ -233,7 +237,9 @@ def convert_to_grayscale(self) -> Image:
 
     def crop(self, x: int, y: int, width: int, height: int) -> Image:
         """
-        Return an image that has been cropped to a given bounding rectangle.
+        Return a new `Image` that has been cropped to a given bounding rectangle.
+
+        The original image is not modified.
 
         Parameters
         ----------
@@ -253,7 +259,9 @@ def crop(self, x: int, y: int, width: int, height: int) -> Image:
 
     def flip_vertically(self) -> Image:
         """
-        Flip the image vertically (horizontal axis, flips up-down and vice versa).
+        Return a new `Image` that is flipped vertically (horizontal axis, flips up-down and vice versa).
+
+        The original image is not modified.
 
         Returns
         -------
@@ -266,7 +274,9 @@ def flip_vertically(self) -> Image:
 
     def flip_horizontally(self) -> Image:
         """
-        Flip the image horizontally (vertical axis, flips left-right and vice versa).
+        Return a new `Ìmage` that is flipped horizontally (vertical axis, flips left-right and vice versa).
+
+        The original image is not modified.
 
         Returns
         -------
@@ -279,7 +289,9 @@ def flip_horizontally(self) -> Image:
 
     def adjust_brightness(self, factor: float) -> Image:
         """
-        Adjust the brightness of an image.
+        Return a new `Image` with an adjusted brightness.
+
+        The original image is not modified.
 
         Parameters
         ----------
@@ -310,7 +322,9 @@ def adjust_brightness(self, factor: float) -> Image:
 
     def add_gaussian_noise(self, standard_deviation: float) -> Image:
         """
-        Add Gaussian noise to the image.
+        Return a new `Image` with Gaussian noise added to the image.
+
+        The original image is not modified.
 
         Parameters
         ----------
@@ -347,7 +361,9 @@ def add_gaussian_noise(self, standard_deviation: float) -> Image:
 
     def adjust_contrast(self, factor: float) -> Image:
         """
-        Adjust Contrast of image.
+        Return a new `Image` with adjusted contrast.
+
+        The original image is not modified.
 
         Parameters
         ----------
@@ -359,7 +375,8 @@ def adjust_contrast(self, factor: float) -> Image:
 
         Returns
         -------
-        New image with adjusted contrast.
+        image: Image
+            New image with adjusted contrast.
         """
         if factor < 0:
             raise OutOfBoundsError(factor, name="factor", lower_bound=ClosedBound(0))
@@ -376,7 +393,9 @@ def adjust_contrast(self, factor: float) -> Image:
 
     def adjust_color_balance(self, factor: float) -> Image:
         """
-        Adjust the image's color balance.
+        Return a new `Image` with adjusted color balance.
+
+        The original image is not modified.
 
         Parameters
         ----------
@@ -406,7 +425,9 @@ def adjust_color_balance(self, factor: float) -> Image:
 
     def blur(self, radius: int) -> Image:
         """
-        Return the blurred image.
+        Return a blurred version of the image.
+
+        The original image is not modified.
 
         Parameters
         ----------
@@ -425,7 +446,9 @@ def blur(self, radius: int) -> Image:
 
     def sharpen(self, factor: float) -> Image:
         """
-        Return the sharpened image.
+        Return a sharpened version of the image.
+
+        The original image is not modified.
 
         Parameters
         ----------
@@ -444,7 +467,9 @@ def sharpen(self, factor: float) -> Image:
 
     def invert_colors(self) -> Image:
         """
-        Return the image with inverted colors.
+        Return a new image with colors inverted.
+
+        The original image is not modified.
 
         Returns
         -------
@@ -457,7 +482,9 @@ def invert_colors(self) -> Image:
 
     def rotate_right(self) -> Image:
         """
-        Return the image rotated 90 degrees clockwise.
+        Return a new `Image` that is rotated 90 degrees clockwise.
+
+        The original image is not modified.
 
         Returns
         -------
@@ -470,7 +497,9 @@ def rotate_right(self) -> Image:
 
     def rotate_left(self) -> Image:
         """
-        Return the image rotated 90 degrees counter-clockwise.
+        Return a new `Image` that is rotated 90 degrees counter-clockwise.
+
+        The original image is not modified.
 
         Returns
         -------
@@ -483,7 +512,9 @@ def rotate_left(self) -> Image:
 
     def find_edges(self) -> Image:
         """
-        Return a grayscale image with the highlighted edges.
+        Return a grayscale version of the image with the edges highlighted.
+
+        The original image is not modified.
 
         Returns
         -------
diff --git a/src/safeds/data/tabular/containers/_column.py b/src/safeds/data/tabular/containers/_column.py
index 9cfdbe402..a0fcc2936 100644
--- a/src/safeds/data/tabular/containers/_column.py
+++ b/src/safeds/data/tabular/containers/_column.py
@@ -490,7 +490,7 @@ def rename(self, new_name: str) -> Column:
         """
         Return a new column with a new name.
 
-        This column is not modified.
+        The original column is not modified.
 
         Parameters
         ----------
@@ -515,7 +515,7 @@ def transform(self, transformer: Callable[[T], R]) -> Column[R]:
         """
         Apply a transform method to every data point.
 
-        This column is not modified.
+        The original column is not modified.
 
         Parameters
         ----------
diff --git a/src/safeds/data/tabular/containers/_row.py b/src/safeds/data/tabular/containers/_row.py
index 5f16ff810..6994b3248 100644
--- a/src/safeds/data/tabular/containers/_row.py
+++ b/src/safeds/data/tabular/containers/_row.py
@@ -453,8 +453,8 @@ def sort_columns(
         """
         Sort the columns of a `Row` with the given comparator and return a new `Row`.
 
-        The original row is not modified. The comparator is a function that takes two tuples of (ColumnName, Value) `col1` and `col2` and
-        returns an integer:
+        The original row is not modified. The comparator is a function that takes two tuples of (ColumnName,
+        Value) `col1` and `col2` and returns an integer:
 
         * If `col1` should be ordered before `col2`, the function should return a negative number.
         * If `col1` should be ordered after `col2`, the function should return a positive number.
diff --git a/src/safeds/data/tabular/containers/_table.py b/src/safeds/data/tabular/containers/_table.py
index ae26a62bc..14b8525b9 100644
--- a/src/safeds/data/tabular/containers/_table.py
+++ b/src/safeds/data/tabular/containers/_table.py
@@ -703,7 +703,7 @@ def summarize_statistics(self) -> Table:
         """
         Return a table with a number of statistical key values.
 
-        This table is not modified.
+        The original table is not modified.
 
         Returns
         -------
@@ -808,8 +808,6 @@ def _as_table(self: Table) -> Table:
         """
         Transform the table to an instance of the Table class.
 
-        The original table is not modified.
-
         Returns
         -------
         table: Table
@@ -819,9 +817,9 @@ def _as_table(self: Table) -> Table:
 
     def add_column(self, column: Column) -> Table:
         """
-        Return the original table with the provided column attached at the end.
+        Return a new table with the provided column attached at the end.
 
-        This table is not modified.
+        The original table is not modified.
 
         Returns
         -------
@@ -858,9 +856,9 @@ def add_column(self, column: Column) -> Table:
 
     def add_columns(self, columns: list[Column] | Table) -> Table:
         """
-        Add multiple columns to the table.
+        Return a new `Table` with multiple added columns.
 
-        This table is not modified.
+        The original table is not modified.
 
         Parameters
         ----------
@@ -906,14 +904,14 @@ def add_columns(self, columns: list[Column] | Table) -> Table:
 
     def add_row(self, row: Row) -> Table:
         """
-        Add a row to the table.
+        Return a new `Table` with an added Row attached.
 
         If the table happens to be empty beforehand, respective columns will be added automatically.
 
         The order of columns of the new row will be adjusted to the order of columns in the table.
         The new table will contain the merged schema.
 
-        This table is not modified.
+        The original table is not modified.
 
         Parameters
         ----------
@@ -962,12 +960,12 @@ def add_row(self, row: Row) -> Table:
 
     def add_rows(self, rows: list[Row] | Table) -> Table:
         """
-        Add multiple rows to a table.
+        Return a new `Table` with multiple added Rows attached.
 
         The order of columns of the new rows will be adjusted to the order of columns in the table.
         The new table will contain the merged schema.
 
-        This table is not modified.
+        The original table is not modified.
 
         Parameters
         ----------
@@ -1018,9 +1016,9 @@ def add_rows(self, rows: list[Row] | Table) -> Table:
 
     def filter_rows(self, query: Callable[[Row], bool]) -> Table:
         """
-        Return a table with rows filtered by Callable (e.g. lambda function).
+        Return a new table with rows filtered by Callable (e.g. lambda function).
 
-        This table is not modified.
+        The original table is not modified.
 
         Parameters
         ----------
@@ -1051,9 +1049,9 @@ def filter_rows(self, query: Callable[[Row], bool]) -> Table:
 
     def group_rows_by(self, key_selector: Callable[[Row], _T]) -> dict[_T, Table]:
         """
-        Return a dictionary with the output tables as values and the keys from the key_selector.
+        Return a dictionary with copies of the output tables as values and the keys from the key_selector.
 
-        This table is not modified.
+        The original table is not modified.
 
         Parameters
         ----------
@@ -1075,9 +1073,9 @@ def group_rows_by(self, key_selector: Callable[[Row], _T]) -> dict[_T, Table]:
 
     def keep_only_columns(self, column_names: list[str]) -> Table:
         """
-        Return a table with only the given column(s).
+        Return a new table with only the given column(s).
 
-        This table is not modified.
+        The original table is not modified.
 
         Note: When removing the last column of the table, the `number_of_columns` property will be set to 0.
 
@@ -1120,9 +1118,9 @@ def keep_only_columns(self, column_names: list[str]) -> Table:
 
     def remove_columns(self, column_names: list[str]) -> Table:
         """
-        Return a table without the given column(s).
+        Return a new table without the given column(s).
 
-        This table is not modified.
+        The original table is not modified.
 
         Note: When removing the last column of the table, the `number_of_columns` property will be set to 0.
 
@@ -1169,9 +1167,9 @@ def remove_columns(self, column_names: list[str]) -> Table:
 
     def remove_columns_with_missing_values(self) -> Table:
         """
-        Return a table without the columns that contain missing values.
+        Return a new table without the columns that contain missing values.
 
-        This table is not modified.
+        The original table is not modified.
 
         Note: When removing the last column of the table, the `number_of_columns` property will be set to 0.
 
@@ -1198,9 +1196,9 @@ def remove_columns_with_missing_values(self) -> Table:
 
     def remove_columns_with_non_numerical_values(self) -> Table:
         """
-        Return a table without the columns that contain non-numerical values.
+        Return a new table without the columns that contain non-numerical values.
 
-        This table is not modified.
+        The original table is not modified.
 
         Note: When removing the last column of the table, the `number_of_columns` property will be set to 0.
 
@@ -1227,9 +1225,9 @@ def remove_columns_with_non_numerical_values(self) -> Table:
 
     def remove_duplicate_rows(self) -> Table:
         """
-        Return a copy of the table with every duplicate row removed.
+        Return a new table with every duplicate row removed.
 
-        This table is not modified.
+        The original table is not modified.
 
         Returns
         -------
@@ -1251,9 +1249,9 @@ def remove_duplicate_rows(self) -> Table:
 
     def remove_rows_with_missing_values(self) -> Table:
         """
-        Return a table without the rows that contain missing values.
+        Return a new table without the rows that contain missing values.
 
-        This table is not modified.
+        The original table is not modified.
 
         Returns
         -------
@@ -1274,13 +1272,13 @@ def remove_rows_with_missing_values(self) -> Table:
 
     def remove_rows_with_outliers(self) -> Table:
         """
-        Remove all rows from the table that contain at least one outlier.
+        Return a new table without those rows that contain at least one outlier.
 
         We define an outlier as a value that has a distance of more than 3 standard deviations from the column mean.
         Missing values are not considered outliers. They are also ignored during the calculation of the standard
         deviation.
 
-        This table is not modified.
+        The original table is not modified.
 
         Returns
         -------
@@ -1319,9 +1317,9 @@ def remove_rows_with_outliers(self) -> Table:
 
     def rename_column(self, old_name: str, new_name: str) -> Table:
         """
-        Rename a single column.
+        Return a new `Table` with a single column renamed.
 
-        This table is not modified.
+        The original table is not modified.
 
         Parameters
         ----------
@@ -1363,11 +1361,11 @@ def rename_column(self, old_name: str, new_name: str) -> Table:
 
     def replace_column(self, old_column_name: str, new_columns: list[Column]) -> Table:
         """
-        Return a copy of the table with the specified old column replaced by a list of new columns.
+        Return a new table with the specified old column replaced by a list of new columns.
 
         The order of columns is kept.
 
-        This table is not modified.
+        The original table is not modified.
 
         Parameters
         ----------
@@ -1422,9 +1420,9 @@ def replace_column(self, old_column_name: str, new_columns: list[Column]) -> Tab
 
     def shuffle_rows(self) -> Table:
         """
-        Shuffle the table randomly.
+        Return a new `Table` with randomly shuffled rows of this `Table`.
 
-        This table is not modified.
+        The original table is not modified.
 
         Returns
         -------
@@ -1456,7 +1454,7 @@ def slice_rows(
         """
         Slice a part of the table into a new table.
 
-        This table is not modified.
+        The original table is not modified.
 
         Parameters
         ----------
@@ -1518,7 +1516,7 @@ def sort_columns(
 
         If no comparator is given, the columns will be sorted alphabetically by their name.
 
-        This table is not modified.
+        The original table is not modified.
 
         Parameters
         ----------
@@ -1560,7 +1558,7 @@ def sort_rows(self, comparator: Callable[[Row, Row], int]) -> Table:
         * If `row1` should be ordered after `row2`, the function should return a positive number.
         * If the original order of `row1` and `row2` should be kept, the function should return 0.
 
-        This table is not modified.
+        The original table is not modified.
 
         Parameters
         ----------
@@ -1600,7 +1598,7 @@ def split_rows(self, percentage_in_first: float) -> tuple[Table, Table]:
         """
         Split the table into two new tables.
 
-        This table is not modified.
+        The original table is not modified.
 
         Parameters
         ----------
@@ -1644,9 +1642,9 @@ def split_rows(self, percentage_in_first: float) -> tuple[Table, Table]:
 
     def tag_columns(self, target_name: str, feature_names: list[str] | None = None) -> TaggedTable:
         """
-        Mark the columns of the table as target column or feature columns. The original table is not modified.
+        Return a new `TaggedTable` with columns marked as a target column or feature columns.
 
-        This table is not modified.
+        The original table is not modified.
 
         Parameters
         ----------
@@ -1679,9 +1677,9 @@ def tag_columns(self, target_name: str, feature_names: list[str] | None = None)
 
     def transform_column(self, name: str, transformer: Callable[[Row], Any]) -> Table:
         """
-        Transform provided column by calling provided transformer.
+        Return a new `Table` with the provided column transformed by calling the provided transformer.
 
-        This table is not modified.
+        The original table is not modified.
 
         Returns
         -------
@@ -1711,9 +1709,9 @@ def transform_column(self, name: str, transformer: Callable[[Row], Any]) -> Tabl
 
     def transform_table(self, transformer: TableTransformer) -> Table:
         """
-        Apply a learned transformation onto this table.
+        Return a new `Table` with a learned transformation applied to this table.
 
-        This table is not modified.
+        The original table is not modified.
 
         Parameters
         ----------
@@ -1749,9 +1747,9 @@ def transform_table(self, transformer: TableTransformer) -> Table:
 
     def inverse_transform_table(self, transformer: InvertibleTableTransformer) -> Table:
         """
-        Invert the transformation applied by the given transformer.
+        Return a new `Table` with the inverted transformation applied by the given transformer.
 
-        This table is not modified.
+        The original table is not modified.
 
         Parameters
         ----------
diff --git a/src/safeds/data/tabular/containers/_tagged_table.py b/src/safeds/data/tabular/containers/_tagged_table.py
index 64f8c86fb..6d1fff246 100644
--- a/src/safeds/data/tabular/containers/_tagged_table.py
+++ b/src/safeds/data/tabular/containers/_tagged_table.py
@@ -194,9 +194,9 @@ def _copy(self) -> TaggedTable:
 
     def add_column_as_feature(self, column: Column) -> TaggedTable:
         """
-        Return the original table with the provided column attached at the end, as a feature column.
+        Return a new table with the provided column attached at the end, as a feature column.
 
-        This table is not modified.
+        the original table is not modified.
 
         Returns
         -------
@@ -218,9 +218,9 @@ def add_column_as_feature(self, column: Column) -> TaggedTable:
 
     def add_columns_as_features(self, columns: list[Column] | Table) -> TaggedTable:
         """
-        Return the original table with the provided columns attached at the end, as feature columns.
+        Return a new `TaggedTable` with the provided columns attached at the end, as feature columns.
 
-        This table is not modified.
+        The original table is not modified.
 
         Returns
         -------
@@ -247,7 +247,7 @@ def add_columns_as_features(self, columns: list[Column] | Table) -> TaggedTable:
 
     def _as_table(self: TaggedTable) -> Table:
         """
-        Remove the tagging from a TaggedTable.
+        Return a new `Table` with the tagging removed.
 
         The original TaggedTable is not modified.
 
@@ -266,9 +266,9 @@ def _as_table(self: TaggedTable) -> Table:
 
     def add_column(self, column: Column) -> TaggedTable:
         """
-        Return the original table with the provided column attached at the end, as neither target nor feature column.
+        Return a new `TaggedTable` with the provided column attached at the end, as neither target nor feature column.
 
-        This table is not modified.
+        The original table is not modified.
 
         Returns
         -------
@@ -290,9 +290,9 @@ def add_column(self, column: Column) -> TaggedTable:
 
     def add_columns(self, columns: list[Column] | Table) -> TaggedTable:
         """
-        Add multiple columns to the table, as neither target nor feature columns.
+        Return a new `TaggedTable` with multiple added columns, as neither target nor feature columns.
 
-        This table is not modified.
+        The original table is not modified.
 
         Parameters
         ----------
@@ -319,9 +319,9 @@ def add_columns(self, columns: list[Column] | Table) -> TaggedTable:
 
     def add_row(self, row: Row) -> TaggedTable:
         """
-        Add a row to the table.
+        Return a new `TaggedTable` with an added Row attached.
 
-        This table is not modified.
+        The original table is not modified.
 
         Parameters
         ----------
@@ -342,9 +342,9 @@ def add_row(self, row: Row) -> TaggedTable:
 
     def add_rows(self, rows: list[Row] | Table) -> TaggedTable:
         """
-        Add multiple rows to the table.
+        Return a new `TaggedTable` with multiple added Rows attached.
 
-        This table is not modified.
+        The original table is not modified.
 
         Parameters
         ----------
@@ -365,9 +365,9 @@ def add_rows(self, rows: list[Row] | Table) -> TaggedTable:
 
     def filter_rows(self, query: Callable[[Row], bool]) -> TaggedTable:
         """
-        Return a table containing only rows that match the given Callable (e.g. lambda function).
+        Return a new `TaggedTable` containing only rows that match the given Callable (e.g. lambda function).
 
-        This table is not modified.
+        The original table is not modified.
 
         Parameters
         ----------
@@ -387,9 +387,9 @@ def filter_rows(self, query: Callable[[Row], bool]) -> TaggedTable:
 
     def keep_only_columns(self, column_names: list[str]) -> TaggedTable:
         """
-        Return a table with only the given column(s).
+        Return a new `TaggedTable` with only the given column(s).
 
-        This table is not modified.
+        The original table is not modified.
 
         Parameters
         ----------
@@ -423,9 +423,9 @@ def keep_only_columns(self, column_names: list[str]) -> TaggedTable:
 
     def remove_columns(self, column_names: list[str]) -> TaggedTable:
         """
-        Remove the given column(s) from the table.
+        Return a new `TaggedTable` with the given column(s) removed from the table.
 
-        This table is not modified.
+        The original table is not modified.
 
         Parameters
         ----------
@@ -461,9 +461,9 @@ def remove_columns(self, column_names: list[str]) -> TaggedTable:
 
     def remove_columns_with_missing_values(self) -> TaggedTable:
         """
-        Remove every column that misses values.
+        Return a new `TaggedTable` with every column that misses values removed.
 
-        This table is not modified.
+        The original table is not modified.
 
         Returns
         -------
@@ -493,9 +493,9 @@ def remove_columns_with_missing_values(self) -> TaggedTable:
 
     def remove_columns_with_non_numerical_values(self) -> TaggedTable:
         """
-        Remove every column that contains non-numerical values.
+        Return a new `TaggedTable` with every column that contains non-numerical values removed.
 
-        This table is not modified.
+        The original table is not modified.
 
         Returns
         -------
@@ -525,9 +525,9 @@ def remove_columns_with_non_numerical_values(self) -> TaggedTable:
 
     def remove_duplicate_rows(self) -> TaggedTable:
         """
-        Remove all row duplicates.
+        Return a new `TaggedTable` with all row duplicates removed.
 
-        This table is not modified.
+        The original table is not modified.
 
         Returns
         -------
@@ -542,9 +542,9 @@ def remove_duplicate_rows(self) -> TaggedTable:
 
     def remove_rows_with_missing_values(self) -> TaggedTable:
         """
-        Return a table without the rows that contain missing values.
+        Return a new `TaggedTable` without the rows that contain missing values.
 
-        This table is not modified.
+        The original table is not modified.
 
         Returns
         -------
@@ -559,13 +559,13 @@ def remove_rows_with_missing_values(self) -> TaggedTable:
 
     def remove_rows_with_outliers(self) -> TaggedTable:
         """
-        Remove all rows from the table that contain at least one outlier.
+        Return a new `TaggedTable` with all rows that contain at least one outlier removed.
 
         We define an outlier as a value that has a distance of more than 3 standard deviations from the column mean.
         Missing values are not considered outliers. They are also ignored during the calculation of the standard
         deviation.
 
-        This table is not modified.
+        The original table is not modified.
 
         Returns
         -------
@@ -580,9 +580,9 @@ def remove_rows_with_outliers(self) -> TaggedTable:
 
     def rename_column(self, old_name: str, new_name: str) -> TaggedTable:
         """
-        Rename a single column.
+        Return a new `TaggedTable` with a single column renamed.
 
-        This table is not modified.
+        The original table is not modified.
 
         Parameters
         ----------
@@ -617,13 +617,13 @@ def rename_column(self, old_name: str, new_name: str) -> TaggedTable:
 
     def replace_column(self, old_column_name: str, new_columns: list[Column]) -> TaggedTable:
         """
-        Replace the specified old column by a list of new columns.
+        Return a new `TaggedTable` with the specified old column replaced by a list of new columns.
 
         If the column to be replaced is the target column, it must be replaced by exactly one column. That column
         becomes the new target column. If the column to be replaced is a feature column, the new columns that replace it
         all become feature columns.
 
-        The order of columns is kept. This table is not modified.
+        The order of columns is kept. The original table is not modified.
 
         Parameters
         ----------
@@ -674,9 +674,9 @@ def replace_column(self, old_column_name: str, new_columns: list[Column]) -> Tag
 
     def shuffle_rows(self) -> TaggedTable:
         """
-        Shuffle the table randomly.
+        Return a new `TaggedTable` with randomly shuffled rows of this table.
 
-        This table is not modified.
+        The original table is not modified.
 
         Returns
         -------
@@ -696,9 +696,9 @@ def slice_rows(
         step: int = 1,
     ) -> TaggedTable:
         """
-        Slice a part of the table into a new table.
+        Slice a part of the table into a new `TaggedTable`.
 
-        This table is not modified.
+        The original table is not modified.
 
         Parameters
         ----------
@@ -742,7 +742,7 @@ def sort_columns(
 
         If no comparator is given, the columns will be sorted alphabetically by their name.
 
-        This table is not modified.
+        The original table is not modified.
 
         Parameters
         ----------
@@ -775,7 +775,7 @@ def sort_rows(self, comparator: Callable[[Row, Row], int]) -> TaggedTable:
         * If the function returns a positive number, `row1` will be ordered after `row2`.
         * If the function returns 0, the original order of `row1` and `row2` will be kept.
 
-        This table is not modified.
+        The original table is not modified.
 
         Parameters
         ----------
@@ -795,9 +795,9 @@ def sort_rows(self, comparator: Callable[[Row, Row], int]) -> TaggedTable:
 
     def transform_column(self, name: str, transformer: Callable[[Row], Any]) -> TaggedTable:
         """
-        Transform provided column by calling provided transformer.
+        Return a new `TaggedTable` with the provided column transformed by calling the provided transformer.
 
-        This table is not modified.
+        The original table is not modified.
 
         Returns
         -------