diff --git a/docs/development/project_guidelines.md b/docs/development/project_guidelines.md index bc706a3..8a9884d 100644 --- 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 index 20a20e5..597e7c9 100644 --- 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 index 5e7e5f6..2d51419 100644 --- 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 index ad2c070..7ef4766 100644 --- 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