various tidyups

packages/Pool_Controls/pool_pump_operation.yaml

@@ -1,10 +1,68 @@
-# packages/poolpump_operation.yaml
+#:########################################################################################:#
+# Pool Pump Operation Package                                                            #
+#:########################################################################################:#
+#
+# TITLE:
+#   Pool Pump Operation
+#
+# FILE:
+#   packages/Pool_Controls/pool_pump_operation.yaml
+#
+# VERSION:
+#   V1.1 2026-07-20
+#
+# VERSION HISTORY:
+#   V1.1 2026-07-20
+#     - Added structured package documentation and section comments.
+#     - Documented the relationship with the native ESPHome controls.
+#
+#   V1.0
+#     - Initial package.
+#     - Provides a Home Assistant UI switch for pool pump BOOST / OFF behaviour.
+#     - Sends TIMER mode again at midnight when required.
+#
+# PURPOSE:
+#   Provides a one-tap Home Assistant UI switch for controlling the pool pump.
+#
+#   Behaviour:
+#     - Turning the UI switch ON sends BOOST if the real pump output is OFF.
+#     - Turning the UI switch OFF sends OFF if the real pump output is ON.
+#     - After OFF is requested, TIMER mode is restored at midnight.
+#     - The UI switch follows the real ESPHome output without publishing MQTT.
+#
+# MQTT:
+#   Operation topic:
+#     viewroad-commands/poolpump-timer/operation
+#
+#   Payloads used by this package:
+#     BOOST
+#     OFF
+#     TIMER
+#
+# DEPENDENCIES:
+#   - switch.esp_poolpumppower_power_output provides the real output state.
+#   - The ESPHome pool pump device subscribes to the MQTT operation topic.
+#   - Native ESPHome mode and boost entities coexist with this one-tap control.
+#
+# NOTES:
+#   - input_boolean.timer_midnight_pending is internal to this package.
+#   - Dashboard cards currently use input_boolean.poolpump_mode_switch.
+#
+#:########################################################################################:#
+
+#:########################################################################################:#
+# Home Assistant Customisation                                                           #
+#:########################################################################################:#
 
 homeassistant:
   customize:
     input_boolean.poolpump_mode_switch:
       icon: mdi:pump
 
+#:########################################################################################:#
+# Input Booleans                                                                         #
+#:########################################################################################:#
+
 input_boolean:
   poolpump_mode_switch:
     name: "Pool Pump Operation"
@@ -14,6 +72,10 @@ input_boolean:
     name: "Send TIMER at Midnight"
     initial: false
 
+#:########################################################################################:#
+# Automations                                                                            #
+#:########################################################################################:#
+
 automation:
   - alias: "Pool Pump → send BOOST when user turns UI switch ON"
     trigger: