Docstrings¶

The docstrings should use the numpydoc format. The 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.

DO:

def add_ints(a: int, b: int) -> int:
    """Add two integers."""
    return a + b

DON'T:

def add_ints(a: int, b: int) -> int:
    """This function adds two integers."""
    return a + b

DON'T:

def add_ints(a: int, b: int) -> int:
    """Adds two integers."""
    return a + b

Modules¶

All modules should have

A one-line description (short summary).
A longer description if needed (extended summary).

Example:

"""Containers for tabular data."""

Classes¶

All public classes should have

A one-line description (short summary).
A longer description if needed (extended summary).
A description of the parameters of their __init__ method (Parameters section). Specify a name and a description, with a colon to separate them. Omit types and default values.
Examples that show how to use them correctly (Examples section).

Example:

"""
A row is a collection of named values.

Parameters
----------
data:
    The data. If None, an empty row is created.

Examples
--------
>>> from safeds.data.tabular.containers import Row
>>> row = Row({"a": 1, "b": 2})
"""

Functions¶

All public functions should have

A one-line description (short summary).
A longer description if needed (extended summary).
A description of their parameters (Parameters section). Specify a name and a description, with a colon to separate them. Omit types and default values.
A description of their results (Returns section). Specify a name and a description, with a colon to separate them. Omit types.
A description of any exceptions that may be raised and under which conditions that may happen (Raises section).
A description of any warnings that may be issued and under which conditions that may happen (Warns section).
Examples that show how to use them correctly (Examples section).

Example:

"""
Return the value of a specified column.

Parameters
----------
column_name:
    The column name.

Returns
-------
value:
    The column value.

Raises
------
UnknownColumnNameError
    If the row does not contain the specified column.

Examples
--------
>>> from safeds.data.tabular.containers import Row
>>> row = Row({"a": 1, "b": 2})
>>> row.get_cell("a")
1
"""