From 993d2a9fd34ce08760933a013e638108827f6f70 Mon Sep 17 00:00:00 2001
From: diogo464 <diogo464@d464.sh>
Date: Sun, 14 Dec 2025 14:49:02 +0000
Subject: Improve documentation and replace publish_on_command with
 CommandPolicy enum
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Enhanced crate-level documentation with comprehensive examples and feature list
- Improved README with badges, better structure, and clearer examples
- Added README.tpl template and generate-readme.sh script for cargo-readme
- Documented run() and connect_and_run() functions with detailed behavior explanations
- Replaced publish_on_command boolean with CommandPolicy enum (PublishState/Manual)
- Added comprehensive documentation for CommandPolicy explaining both modes

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
---
 src/command_policy.rs | 79 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 79 insertions(+)
 create mode 100644 src/command_policy.rs

(limited to 'src/command_policy.rs')

diff --git a/src/command_policy.rs b/src/command_policy.rs
new file mode 100644
index 0000000..049d56a
--- /dev/null
+++ b/src/command_policy.rs
@@ -0,0 +1,79 @@
+/// Determines how an entity handles commands received from Home Assistant.
+///
+/// This policy controls whether an entity automatically publishes its state when it receives
+/// a command from Home Assistant, or if the application should handle state updates manually.
+///
+/// # Variants
+///
+/// ## `PublishState` (Default)
+///
+/// When a command is received from Home Assistant, the entity automatically:
+/// 1. Updates its internal state to match the command value
+/// 2. Publishes the new state back to Home Assistant
+///
+/// This is useful for simple entities where the command should immediately be reflected as the
+/// current state, such as:
+/// - A switch that turns on/off immediately when commanded
+/// - A number input that updates its value when changed in the UI
+///
+/// ## `Manual`
+///
+/// When a command is received from Home Assistant, the entity:
+/// 1. Stores the command for the application to read via `wait()` or `command()`
+/// 2. Does NOT automatically update or publish the state
+///
+/// The application must manually update the entity's state after processing the command.
+/// This is useful when:
+/// - The command triggers an action that may fail (e.g., turning on a motor)
+/// - The actual state may differ from the commanded state
+/// - You need to validate or transform the command before applying it
+///
+/// # Examples
+///
+/// ## Auto-publish (default)
+///
+/// ```no_run
+/// # use embassy_ha::{CommandPolicy, SwitchConfig};
+/// let config = SwitchConfig {
+///     command_policy: CommandPolicy::PublishState, // or just use default
+///     ..Default::default()
+/// };
+/// // When Home Assistant sends "ON", the switch state automatically becomes "ON"
+/// ```
+///
+/// ## Manual control
+///
+/// ```no_run
+/// # use embassy_ha::{CommandPolicy, SwitchConfig, BinaryState, Switch};
+/// # async fn example(mut switch: Switch<'_>) {
+/// let config = SwitchConfig {
+///     command_policy: CommandPolicy::Manual,
+///     ..Default::default()
+/// };
+///
+/// loop {
+///     let command = switch.wait().await;
+///
+///     // Try to perform the action
+///     if turn_on_motor().await.is_ok() {
+///         // Only update state if the action succeeded
+///         switch.set(command);
+///     }
+/// }
+/// # }
+/// # async fn turn_on_motor() -> Result<(), ()> { Ok(()) }
+/// ```
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum CommandPolicy {
+    /// Automatically publish the entity's state when a command is received.
+    PublishState,
+
+    /// Do not automatically publish state. The application must manually update the state.
+    Manual,
+}
+
+impl Default for CommandPolicy {
+    fn default() -> Self {
+        Self::PublishState
+    }
+}
-- 
cgit