improve comments

Signed-off-by: Victor Garcia Reolid <victor@seita.nl>

flexmeasures/data/models/planning/storage.py

@@ -249,7 +249,10 @@ def _prepare(self, skip_validation: bool = False) -> tuple:  # noqa: C901
                     beliefs_before=belief_time,
                 )
 
-                stock_delta_series *= resolution / timedelta(hours=1)  # MW -> MW
+                # example: 4 MW sustained over 15 minutes gives 1 MWh
+                stock_delta_series *= resolution / timedelta(
+                    hours=1
+                )  # MW -> MWh / resolution
 
                 if is_usage:
                     stock_delta_series *= -1

flexmeasures/data/models/planning/tests/conftest.py

@@ -222,10 +222,13 @@ def process(db, building, setup_sources) -> dict[str, Sensor]:
 @pytest.fixture(scope="module")
 def add_stock_delta(db, add_battery_assets, setup_sources) -> dict[str, Sensor]:
     """
-    Set up the same constant delta (capacity_in_mw) in different resolutions.
-
-    In 15 min event resolution, the maximum energy that the battery can produce/consume in period
-    is 0.25 * capacity_in_mw
+    Different usage forecast sensors are defined:
+        - "delta fails": the usage forecast exceeds the maximum power.
+        - "delta": the usage forecast can be fulfilled just right. This coincides with the schedule resolution.
+        - "delta hourly": the event resolution is changed to test that the schedule is still feasible.
+                          This has a greater resolution.
+        - "delta 5min": the event resolution is reduced even more. This sensor has a resolution smaller than the used
+                        for the scheduler.
     """
 
     battery = add_battery_assets["Test battery"]

flexmeasures/data/models/planning/tests/test_solver.py

@@ -1458,12 +1458,20 @@ def test_battery_stock_delta_sensor(
     add_battery_assets, add_stock_delta, stock_delta_sensor
 ):
     """
-    Test the soc delta feature using sensors.
+    Test the SOC delta feature using sensors.
 
     An empty battery is made to fulfill a usage signal under a flat tariff.
     The battery is only allowed to charge (production-capacity = 0).
 
-    We expect the storage to charge in every period to compensate for the usage.
+    Set up the same constant delta (capacity_in_mw) in different resolutions.
+
+    The problem is defined with the following settings:
+        - Battery empty at the start of the schedule (soc-at-start = 0).
+        - Battery of size 2 MWh.
+        - Consumption capacity of the battery is 2 MW.
+        - The battery cannot discharge.
+    With these settings, the battery needs to charge at a power or greater than the usage forecast
+    to keep the SOC within bounds ([0, 2 MWh]).
     """
     _, battery = get_sensors_from_db(add_battery_assets)
     tz = pytz.timezone("Europe/Amsterdam")