docs: remove type hints (#125)

### Summary of Changes Remove type hints in docstrings. These are redundant, since types are already specified in the code. --------- Co-authored-by: megalinter-bot <[email protected]>
Safe-DS · Jan 25, 2024 · ca21f09 · ca21f09
1 parent df74160
commit ca21f09
Show file tree

Hide file tree

Showing 4 changed files with 40 additions and 60 deletions.
diff --git a/docs/development/project_guidelines.md b/docs/development/project_guidelines.md
@@ -1,12 +1,13 @@
 # Project Guidelines
 
-This document describes general guidelines for the Safe-DS Python Library - Examples.
+This document describes general guidelines for the Safe-DS Python Library Examples.
 
 ## Docstrings
 
 The docstrings **should** use the [numpydoc](https://numpydoc.readthedocs.io/en/latest/format.html) format. The
-descriptions **should not** start with "this" and **should** use imperative mood. Refer to the subsections below for
-more details on how to document specific API elements.
+descriptions **should not** start with "this" and **should** use imperative mood. Docstrings **should not** contain
+type hints, since they are already specified in the code. Refer to the subsections below for more details on how to
+document specific API elements.
 
 !!! success "**DO**:"
 
@@ -32,39 +33,12 @@ more details on how to document specific API elements.
         return a + b
     ```
 
-!!! success "**DO**:"
-
-    ```py
-    def __init__(self, data: Mapping[str, Any] | None = None) -> None:
-        """
-        data : Mapping[str, Any] | None
-        """
-    ```
-
-!!! failure "**DON'T**:"
-
-    ```py
-    def __init__(self, data: Optional[Mapping[str, Any]] = None) -> None:
-        """
-        data : Optional[Mapping[str, Any]]
-        """
-    ```
-
-!!! failure "**DON'T**:"
-
-    ```py
-    def __init__(self, data: Mapping[str, Any] | None = None) -> None:
-        """
-        data : Optional[Mapping[str, Any]]
-        """
-    ```
-
 ### Modules
 
 All modules should have
 
-* a one-line description ([short summary][short-summary-section]),
-* a longer description if needed ([extended summary][extended-summary-section]).
+* A one-line description ([short summary][short-summary-section]).
+* A longer description if needed ([extended summary][extended-summary-section]).
 
 Example:
 
@@ -76,10 +50,11 @@ Example:
 
 All classes should have
 
-* a one-line description ([short summary][short-summary-section]),
-* a longer description if needed ([extended summary][extended-summary-section])
-* a description of the parameters of their `__init__` method ([`Parameters` section][parameters-section]),
-* examples that show how to use them correctly ([`Examples` section][examples-section]).
+* A one-line description ([short summary][short-summary-section]).
+* A longer description if needed ([extended summary][extended-summary-section]).
+* A description of the parameters of their `__init__` method ([`Parameters` section][parameters-section]). Omit types
+and default values.
+* Examples that show how to use them correctly ([`Examples` section][examples-section]).
 
 Example:
 
@@ -89,7 +64,7 @@ A row is a collection of named values.
 
 Parameters
 ----------
-data : Mapping[str, Any] | None
+data
     The data. If None, an empty row is created.
 
 Examples
@@ -103,15 +78,17 @@ Examples
 
 All functions should have
 
-* a one-line description ([short summary][short-summary-section]),
-* a longer description if needed ([extended summary][extended-summary-section])
-* a description of their parameters ([`Parameters` section][parameters-section]),
-* a description of their results ([`Returns` section][returns-section]),
-* a description of any exceptions that may be raised and under which conditions that may
-  happen ([`Raises` section][raises-section]),
-* a description of any warnings that may be issued and under which conditions that may
-  happen ([`Warns` section][warns-section]),
-* examples that show how to use them correctly ([`Examples` section][examples-section]).
+* A one-line description ([short summary][short-summary-section]).
+* A longer description if needed ([extended summary][extended-summary-section]).
+* A description of their parameters ([`Parameters` section][parameters-section]). Omit types
+  and default values.
+* A description of their results ([`Returns` section][returns-section]). Specify a name for the return value but omit
+  its type. Note that the colon after the name is required here, otherwise it will be interpreted as a type.
+* A description of any exceptions that may be raised and under which conditions that may
+  happen ([`Raises` section][raises-section]).
+* A description of any warnings that may be issued and under which conditions that may
+  happen ([`Warns` section][warns-section]).
+* Examples that show how to use them correctly ([`Examples` section][examples-section]).
 
 Example:
 
@@ -121,12 +98,12 @@ Return the value of a specified column.
 
 Parameters
 ----------
-column_name : str
+column_name
     The column name.
 
 Returns
 -------
-value : Any
+value :
     The column value.
 
 Raises
@@ -234,8 +211,8 @@ adding new classes to it.
     ]
     ```
 
-[src-folder]: https://github.com/Safe-DS/Library/tree/main/src
-[tests-folder]: https://github.com/Safe-DS/Library/tree/main/tests
+[src-folder]: https://github.com/Safe-DS/Library-Examples/tree/main/src
+[tests-folder]: https://github.com/Safe-DS/Library-Examples/tree/main/tests
 [short-summary-section]: https://numpydoc.readthedocs.io/en/latest/format.html#short-summary
 [extended-summary-section]: https://numpydoc.readthedocs.io/en/latest/format.html#extended-summary
 [parameters-section]: https://numpydoc.readthedocs.io/en/latest/format.html#parameters

diff --git a/src/safeds_examples/tabular/_house_sales/_house_sales.py b/src/safeds_examples/tabular/_house_sales/_house_sales.py
@@ -13,7 +13,7 @@ def load_house_sales() -> ExampleTable:
 
     Returns
     -------
-    ExampleTable
+    house_sales :
         The "House Sales" dataset.
     """
     return ExampleTable(
@@ -32,15 +32,18 @@ def load_house_sales() -> ExampleTable:
             "sqft_basement": "Interior living space below ground in square feet",
             "floors": "Number of floors",
             "bedrooms": "Number of bedrooms",
-            "bathrooms": "Number of bathrooms.\n\n"
-            "Fractional values indicate that components (toilet/sink/shower/bathtub) are missing.",
+            "bathrooms": (
+                "Number of bathrooms.\n\n"
+                "Fractional values indicate that components (toilet/sink/shower/bathtub) are missing."
+            ),
             "waterfront": "Whether the building overlooks a waterfront (0 = no, 1 = yes)",
             "view": "Rating of the view (1 to 5, higher is better)",
             "condition": "Rating of the condition of the house (1 to 5, higher is better)",
             "grade": "Rating of building construction and design (1 to 13, higher is better)",
             "year_built": "Year the house was built",
-            "year_renovated": "Year the house was last renovated.\n\n"
-            "A value of 0 indicates that it was never renovated.",
+            "year_renovated": (
+                "Year the house was last renovated.\n\nA value of 0 indicates that it was never renovated."
+            ),
             "sqft_lot_15nn": "Lot area of the 15 nearest neighbors in square feet",
             "sqft_living_15nn": "Interior living space of the 15 nearest neighbors in square feet",
             "price": "Price the house sold for in USD",

diff --git a/src/safeds_examples/tabular/_titanic/_titanic.py b/src/safeds_examples/tabular/_titanic/_titanic.py
@@ -13,7 +13,7 @@ def load_titanic() -> ExampleTable:
 
     Returns
     -------
-    ExampleTable
+    titanic :
         The "Titanic" dataset.
     """
     return ExampleTable(

diff --git a/src/safeds_examples/tabular/containers/_example_table.py b/src/safeds_examples/tabular/containers/_example_table.py
@@ -8,9 +8,9 @@ class ExampleTable(Table):
 
     Parameters
     ----------
-    table : Table
+    table
         The table.
-    column_descriptions : dict[str, str]
+    column_descriptions
         A dictionary mapping column names to their descriptions.
 
     Raises
@@ -50,12 +50,12 @@ def get_column_description(self, column_name: str) -> str:
 
         Parameters
         ----------
-        column_name : str
+        column_name
             The name of the column.
 
         Returns
         -------
-        description : str
+        column_description :
             The description of the column.
 
         Raises