The Python project owns its momentum calculation and inference meaning. The Compiled project relies on package-defined ROC, target, scaler and replay contracts. Document each callable at the boundary it actually owns.
This page applies when a public function, class, or method changes. The goal is code-true guidance that lets future contributors and users answer basic questions without opening the implementation.
Prerequisites
- the current implementation and tests for the documented callable
- the Limen development environment for lint and type checks
When a docstring is required
Update or add a docstring when a change touches:
- a public function
- a public class
- a public method with real behavioral surface
- a public helper whose arguments, outputs, or side effects matter to callers
If behavior changed, the docstring should change with it.
House style
Follow the current callable and its behavior. For example, the Compiled project consumes ROC; its source-bound signature is:
def roc(data: pl.DataFrame, price_col: str='close', period: int=10) -> pl.DataFrame: ...Read the ROC implementation and docstring for its input columns, output naming and warm-up behavior. The Python project owns its momentum function; do not present that caller decision as a package guarantee.
Current expectations:
- use a short summary first
- document meaningful arguments under
Args: - document return behavior under
Returns: - keep the wording direct and concrete
What docstrings include
A Limen docstring should answer:
- what the function or class does
- what inputs it expects
- what it returns or mutates
- what columns it adds or requires when the surface is DataFrame-based
- units and domains, warm-up/null behavior and observation availability
- which state fits on training and how later calls reuse it
- meaningful refusals, optional dependencies and supported combinations
- caveats that affect caller behavior
What to avoid
- repeating the function name without adding meaning
- documenting obvious assignments line by line
- leaving stale parameter names after a refactor
- describing future intended behavior as if it already exists
- hiding important side effects such as overwriting a column or depending on train-fitted state
DataFrame-specific guidance
Much of Limen's public surface is Polars-based. For those functions, docstrings should specify:
- required input columns
- output column names or naming patterns
- whether rows are filtered, appended, or only transformed
- whether the helper is stateless or fitted on train data
A public contract change also updates its canonical reference and every applicable project case. A matching signature alone does not establish input semantics, causality or execution. Keep those meanings authored at their source; use the exact bindings and independent result assertions described in the documentation contract.
Review standard
Docstring review checks that the text remains true after the change, names the relevant columns, params, or artifacts, and gives callers enough information without opening the implementation.