diff --git a/docs/development/project_guidelines.md b/docs/development/project_guidelines.md index 49e96bfd..8c17a8ce 100644 --- a/docs/development/project_guidelines.md +++ b/docs/development/project_guidelines.md @@ -5,8 +5,9 @@ This document describes general guidelines for the Safe-DS Stub Generator. ## 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/Stub-Generator/tree/main/src +[tests-folder]: https://github.com/Safe-DS/Stub-Generator/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