diff --git a/flixopt/calculation.py b/flixopt/calculation.py
index 22577ef59..de62f47f9 100644
--- a/flixopt/calculation.py
+++ b/flixopt/calculation.py
@@ -207,6 +207,7 @@ class AggregatedCalculation(FullCalculation):
             This equalizes variables in the components according to the typical periods computed in the aggregation
         active_timesteps: DatetimeIndex of timesteps to use for calculation. If None, all timesteps are used
         folder: Folder where results should be saved. If None, current working directory is used
+        aggregation: contains the aggregation model
     """
 
     def __init__(
diff --git a/flixopt/components.py b/flixopt/components.py
index 37f1da8b9..1df7d7b92 100644
--- a/flixopt/components.py
+++ b/flixopt/components.py
@@ -580,6 +580,19 @@ def relative_charge_state_bounds(self) -> Tuple[NumericData, NumericData]:
 class SourceAndSink(Component):
     """
     class for source (output-flow) and sink (input-flow) in one commponent
+    A SourceAndSink consumes AND provides energy or material flows from and to the system.
+
+    Sources can represent markets where energy or material can be bought or sold.
+
+    Args:
+        label: The label of the Element. Used to identify it in the FlowSystem
+        inputs: Input-flows into the SourceAndSink
+        outputs: Output-flows from the SourceAndSink
+        prevent_simultaneous_flow_rates: If True, only one output flow can be active at a time
+                meta_data: Used to store more information about the Element. Is not used internally, but saved in the results. Only use python native types.
+
+    Deprecated:
+        The deprecated `sink` and `source` kwargs are accepted for compatibility but will be removed in future releases.
     """
 
     def __init__(
@@ -676,6 +689,9 @@ class Source(Component):
         outputs: Output-flows from the source
         meta_data: Used to store more information about the Element. Is not used internally, but saved in the results. Only use python native types.
         prevent_simultaneous_flow_rates: If True, only one output flow can be active at a time
+
+    Deprecated:
+        The deprecated `source` kwarg is accepted for compatibility but will be removed in future releases.
     """
 
     def __init__(
@@ -727,6 +743,9 @@ class Sink(Component):
         inputs: Input-flows into the sink
         meta_data: Used to store more information about the Element. Is not used internally, but saved in the results. Only use python native types.
         prevent_simultaneous_flow_rates: If True, only one input flow can be active at a time
+
+    Deprecated:
+        The deprecated `sink` kwarg is accepted for compatibility but will be removed in future releases.
     """
 
     def __init__(
@@ -737,6 +756,20 @@ def __init__(
         prevent_simultaneous_flow_rates: bool = False,
         **kwargs,
     ):
+        """
+        Initialize a Sink (consumes flow from the system).
+
+        Supports legacy `sink=` keyword for backward compatibility (deprecated): if `sink` is provided it is used as the single input flow and a DeprecationWarning is issued; specifying both `inputs` and `sink` raises ValueError.
+
+        Parameters:
+            label (str): Unique element label.
+            inputs (List[Flow], optional): Input flows for the sink.
+            meta_data (dict, optional): Arbitrary metadata attached to the element.
+            prevent_simultaneous_flow_rates (bool, optional): If True, prevents simultaneous nonzero flow rates across the element's inputs by wiring that restriction into the base Component setup.
+
+        Note:
+            The deprecated `sink` kwarg is accepted for compatibility but will be removed in future releases.
+        """
         sink = kwargs.pop('sink', None)
         if sink is not None:
             warnings.warn(
diff --git a/flixopt/effects.py b/flixopt/effects.py
index 19cbeaa4a..8ed82a24c 100644
--- a/flixopt/effects.py
+++ b/flixopt/effects.py
@@ -46,6 +46,10 @@ class Effect(Element):
         minimum_total: Min sum of effect (invest+operation)
         maximum_total: Max sum of effect (invest+operation)
         meta_data: Used to store more information about the Element. Is not used internally, but saved in the results. Only use python native types.
+
+    Notes:
+        - Bounds may be None to indicate unbounded in that direction.
+        - The unit of the effect is only informative and does not affect the optimization.
     """
 
     def __init__(
diff --git a/flixopt/elements.py b/flixopt/elements.py
index 283d0cef9..1b444b11e 100644
--- a/flixopt/elements.py
+++ b/flixopt/elements.py
@@ -102,6 +102,10 @@ class Bus(Element):
             (none/ 0 -> no penalty). The default is 1e5.
             (Take care: if you use a timeseries (no scalar), timeseries is aggregated if calculation_type = aggregated!)
         meta_data: used to store more information about the Element. Is not used internally, but saved in the results. Only use python native types.
+
+    Notes:
+        The constructor also initializes empty `inputs` and `outputs` lists for connected Flow objects.
+        The registration of connections is handled automatically by the FlowSystem.
     """
 
     def __init__(
@@ -150,6 +154,13 @@ class Flow(Element):
     A **Flow** moves energy (or material) between a [Bus][flixopt.elements.Bus] and a [Component][flixopt.elements.Component] in a predefined direction.
     The flow-rate is the main optimization variable of the **Flow**.
 
+    Notes:
+       - If `size` is None, a large default (CONFIG.modeling.BIG) is used.
+       - If `previous_flow_rate` is provided as a list, it is converted to a NumPy array.
+
+    Deprecated:
+        - Passing a Bus object to `bus` is deprecated. Pass the bus label string instead.
+
     Args:
         label: The label of the Flow. Used to identify it in the FlowSystem. Its `full_label` consists of the label of the Component and the label of the Flow.
         bus: Label of the bus the flow is connected to.
diff --git a/flixopt/flow_system.py b/flixopt/flow_system.py
index e4887053c..657d30f87 100644
--- a/flixopt/flow_system.py
+++ b/flixopt/flow_system.py
@@ -40,6 +40,10 @@ class FlowSystem:
             If None, the first time increment of time_series is used.
             This is needed to calculate previous durations (for example consecutive_on_hours).
             If you use an array, take care that its long enough to cover all previous values!
+
+    Notes:
+        - Creates an empty registry for components and buses, an empty EffectCollection, and a placeholder for a SystemModel.
+        - The instance starts disconnected (self._connected == False) and will be connected automatically when trying to solve a calculation.
     """
 
     def __init__(
@@ -48,6 +52,19 @@ def __init__(
         hours_of_last_timestep: Optional[float] = None,
         hours_of_previous_timesteps: Optional[Union[int, float, np.ndarray]] = None,
     ):
+        """
+        Initialize a FlowSystem that manages components, buses, effects, and their time-series.
+
+        Parameters:
+            timesteps: DatetimeIndex defining the primary timesteps for the system's TimeSeriesCollection.
+            hours_of_last_timestep: Duration (in hours) of the final timestep; if None, inferred from timesteps or defaults in TimeSeriesCollection.
+            hours_of_previous_timesteps: Scalar or array-like durations (in hours) for the preceding timesteps; used to configure non-uniform timestep lengths.
+
+        Notes:
+            Creates an empty registry for components and buses, an empty EffectCollection, and a placeholder for a SystemModel.
+            The instance starts disconnected (self._connected == False) and with no active network visualization app.
+            This can also be triggered manually with `_connect_network()`.
+        """
         self.time_series_collection = TimeSeriesCollection(
             timesteps=timesteps,
             hours_of_last_timestep=hours_of_last_timestep,
diff --git a/flixopt/interface.py b/flixopt/interface.py
index 1b240bc4b..78a50f181 100644
--- a/flixopt/interface.py
+++ b/flixopt/interface.py
@@ -161,6 +161,12 @@ def __init__(self, pieces: List[Piece]):
         self.pieces = pieces
 
     def __len__(self):
+        """
+        Return the number of Piece segments in this Piecewise container.
+
+        Returns:
+            int: Count of contained Piece objects.
+        """
         return len(self.pieces)
 
     def __getitem__(self, index) -> Piece:
@@ -341,6 +347,12 @@ def __init__(self, piecewises: Dict[str, Piecewise]):
         self.piecewises = piecewises
 
     def items(self):
+        """
+        Return an iterator over (flow_label, Piecewise) pairs stored in this PiecewiseConversion.
+
+        This is a thin convenience wrapper around the internal mapping and yields the same view
+        as dict.items(), where each key is a flow label (str) and each value is a Piecewise.
+        """
         return self.piecewises.items()
 
     def transform_data(self, flow_system: 'FlowSystem', name_prefix: str):