Skip to content
This repository has been archived by the owner on Nov 23, 2024. It is now read-only.

Commit

Permalink
docs: remove type hints (#125)
Browse files Browse the repository at this point in the history
### Summary of Changes

Remove type hints in docstrings. These are redundant, since types are
already specified in the code.

---------

Co-authored-by: megalinter-bot <129584137+megalinter-bot@users.noreply.github.com>
  • Loading branch information
lars-reimann and megalinter-bot authored Jan 25, 2024
1 parent df74160 commit ca21f09
Show file tree
Hide file tree
Showing 4 changed files with 40 additions and 60 deletions.
77 changes: 27 additions & 50 deletions docs/development/project_guidelines.md
Original file line number Diff line number Diff line change
@@ -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**:"

Expand All @@ -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:

Expand All @@ -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:

Expand All @@ -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
Expand All @@ -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:

Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down
13 changes: 8 additions & 5 deletions src/safeds_examples/tabular/_house_sales/_house_sales.py
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ def load_house_sales() -> ExampleTable:
Returns
-------
ExampleTable
house_sales :
The "House Sales" dataset.
"""
return ExampleTable(
Expand All @@ -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",
Expand Down
2 changes: 1 addition & 1 deletion src/safeds_examples/tabular/_titanic/_titanic.py
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ def load_titanic() -> ExampleTable:
Returns
-------
ExampleTable
titanic :
The "Titanic" dataset.
"""
return ExampleTable(
Expand Down
8 changes: 4 additions & 4 deletions src/safeds_examples/tabular/containers/_example_table.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down

0 comments on commit ca21f09

Please sign in to comment.