Skip to content

Documentation decorator

David Schäfer requested to merge docurator into develop

This MR adds a decorator, which injects the common parameters field, target, dfilter, flag into the docstring of the decorated function. The idea is to reduce duplication in the documentation and to provide identical description.

This turns this:

"""
Function flags values exceeding the closed interval [`min`, `max`].

Parameters
----------
min : float
    Lower bound for valid data.
max : float
    Upper bound for valid data.y
"""

into this:

"""
Function flags values exceeding the closed interval [`min`, `max`].


Parameters
----------
field : str | List[str]
    variable to process
min : float
    Lower bound for valid data.
max : float
    Upper bound for valid data.
target : str | List[str], optional
    variable to write function results to, if not given 'target' equals 'field', will be created if not existing
dfilter : Any, optional
    masking threshold, if not given the default `DFILTER_ALL` value of the translation scheme
flag : Any, optional
    flag to set, if not given the default `BAD` value of the translation scheme

Returns
-------
SaQC : saqc.SaQC
    the updated SaQC object

If there is interest, I would go through all functions and adapt the docstrings accordingly. While doing this, I could also address #394 (closed).

Note: The current parameter descriptions are not yet finalized and are subject to change. Ideas are welcome...

What do you think @palmb and @luenensc ?

Edited by David Schäfer

Merge request reports