Documentation decorator
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 objectIf 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...
Merge request reports
Activity
changed milestone to %2.4.0
added category: documentation label
assigned to @schaefed
added 2 commits
Really like the idea - especially because parameter descriptions of the global kwargs differ from function to function or are sometimes more or less present.
We could also implement this functionality as part of
registerinstead of a separate decorator...I would stick to the existing
registerfunction, just for the sake of it might start get feeling baroque to have evermore decorators in the code (so dont really have insight in the implications)I could also address #394 (closed).
i think its good to do this on the go just to avoid mc salad
added 19 commits
- 7091e73c - adapted docstrings
- 521a1aa4 - adapted docstrings
- 069c97b2 - adapted docstrings
- eba9755c - adapted docstrings
- 724d2ee7 - adapted docstrings
- 0d357bd3 - adapted docstrings
- 71f11efb - adapted docstrings
- ffd4bfea - adapted docstrings
- 78a2cf15 - adapted docstrings
- c08b3ce6 - adapted docstrings
- fb5ef426 - adapted docstrings
- 5b42b511 - adapted docstrings
- f0a6569d - adapted docstrings
- e8bcd950 - adpated docstrings
- 5378d1f1 - adapted docstrings
- d1d7911a - adapted docstring
- a8953b8a - adapte ddocstrings
- 31bd0844 - leftovers
- b27f75ed - compliance
Toggle commit list
