docs: update guidelines regarding docstrings

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