Documentation¶

CEM-012

🤖 CEM-012-000 Function Docstrings¶

Specification¶

All functions MUST HAVE a docstring

the docstring MUST BE in .rst format

the docsrting MUST FOLLOW the following template:

def functionName(parameters) -> return type:
    """
    Concise (one-line) description of the function.

    Extended description of the function, if necessary.

    Parameters
    ----------

    parameters : type
        Description of the parameters.

    Throws (optional)
    -----------------

    ExceptionType
        Description of the exception condition.

    Side Effects (optional)
    -----------------------

    Description of any side effects.

    Returns
    -------

    return type
        Description of the return value.

    Examples
    --------

    >>> result = functionName(example_parameter)
    >>> print(result)
    42
    """

🤖 CEM-012-001 Module Docstrings¶

Specification¶

All modules MUST HAVE a docstring
the docstring MUST BE in .rst format
the docstring MUST FOLLOW the following template:

"""
Short summary describing the module's purpose.

Optional longer description with context, constraints, and side effects.

Public API
----------
- :class:`MyClass`: Brief role.
- :func:`do_thing`: Primary operation.
- :data:`DEFAULTS`: Configuration constants.

Attributes
----------
DEFAULTS : dict
    Default configuration values used across the module.

Examples
--------
>>> from mypkg.mymodule import do_thing
>>> result = do_thing("input")
>>> print(result)
42

See Also
--------
:meth:`MyClass.run`, :mod:`mypkg.othermodule`
"""