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 <[email protected]> Co-authored-by: megalinter-bot <[email protected]>
Safe-DS · Jul 13, 2023 · 62e8fe9 · 62e8fe9
1 parent 925a505
commit 62e8fe9
Show file tree

Hide file tree

Showing 5 changed files with 137 additions and 108 deletions.
diff --git 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
@@ -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
@@ -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.