feat: enhance code documentation and add comprehensive unit tests

- Add detailed rustdoc comments to all public APIs and structs
- Improve error messages with actionable guidance and context
- Optimize release profile with size optimizations and LTO
- Add unit tests for command parsing and validation
- Update AGENTS.md with official OBS WebSocket spec reference

Author: g

AGENTS.md

@@ -5,6 +5,7 @@
 - **obws**: OBS WebSocket client library
 - **clap**: Command-line argument parsing
 - **tokio**: Async runtime
+- The official obs-websocket spec https://raw.githubusercontent.com/obsproject/obs-websocket/master/docs/generated/protocol.md
 
 ## Project Structure
 ```

Cargo.lock

@@ -4,16 +4,23 @@ version = "0.20.3"
 edition = "2021"
 description = "A minimal command to control obs via obs-websocket"
 authors = ["Luigi Maselli <luigi@grigio.org>"]
-rust-version = "1.88.0"
+
 license = "MIT"
 
 [[bin]]
 name = "obs-cmd"
 
 [dependencies]
-tokio = { version = "1.42", features = ["rt-multi-thread", "macros", "time"] }
+tokio = { version = "1.42", features = ["rt-multi-thread", "macros", "time"], default-features = false }
 obws = "0.14"
 clap = { version = "4.5", features = ["derive"] }
 url = "2.5"
 time = "0.3.37"
 thiserror = "2.0"
+
+[profile.release]
+opt-level = "z"
+lto = true
+codegen-units = 1
+panic = "abort"
+strip = true

Cargo.toml

@@ -3,10 +3,17 @@ use std::path::PathBuf;
 use std::str::FromStr;
 use url::Url;
 
+/// OBS WebSocket connection configuration.
+/// 
+/// This struct represents the connection parameters for connecting
+/// to an OBS WebSocket server, typically parsed from a URL string.
 #[derive(Clone, Debug)]
 pub struct ObsWebsocket {
+    /// Hostname or IP address of the OBS WebSocket server
     pub hostname: String,
+    /// Port number where OBS WebSocket is listening
     pub port: u16,
+    /// Optional password for OBS WebSocket authentication
     pub password: Option<String>,
 }
 
@@ -106,19 +113,48 @@ pub enum SceneCollection {
     Switch { scene_collection_name: String },
 }
 
+/// Command-line interface for obs-cmd.
+/// 
+/// This struct defines the main CLI interface using clap for parsing.
+/// It supports connecting to OBS WebSocket and executing various commands.
+/// 
+/// # Examples
+/// 
+/// ```bash
+/// # Get OBS version info
+/// obs-cmd info
+/// 
+/// # Start recording
+/// obs-cmd recording start
+/// 
+/// # Switch to a scene
+/// obs-cmd scene switch "Main Scene"
+/// 
+/// # Connect to custom OBS WebSocket
+/// obs-cmd --websocket obsws://192.168.1.100:4455/password info
+/// ```
 #[derive(Parser)]
 #[clap(author, version, about, long_about = None)]
 pub struct Cli {
+    /// OBS WebSocket connection URL.
+    /// 
+    /// If not provided, defaults to `obsws://localhost:4455/secret`.
+    /// Can also be set via OBS_WEBSOCKET_URL environment variable.
     #[clap(short, long)]
-    /// The default websocket URL is `obsws://localhost:4455/secret`
-    /// if this argument is not provided
     pub websocket: Option<ObsWebsocket>,
+    
+    /// The command to execute on OBS.
     #[clap(subcommand)]
     pub command: Commands,
 }
 
+/// Available commands for controlling OBS.
+/// 
+/// This enum represents all possible operations that can be performed
+/// on OBS Studio via the WebSocket interface.
 #[derive(Subcommand)]
 pub enum Commands {
+    /// Get OBS Studio version and information
     Info,
     #[clap(subcommand)]
     Scene(Scene),
@@ -220,10 +256,25 @@ pub enum MediaInput {
     },
 }
 
-// Parses strings of such format:
-// 0:00 -> 0 seconds
-// 01:00 -> 1 minute
-// 1:00:00 -> 1 hour
+/// Parses duration strings in [hh:]mm:ss format.
+/// 
+/// This function converts human-readable time strings into Duration objects.
+/// Supports both minute:second and hour:minute:second formats.
+/// 
+/// # Examples
+/// 
+/// * "0:00" -> 0 seconds
+/// * "01:00" -> 1 minute  
+/// * "1:00:00" -> 1 hour
+/// * "1:30:45" -> 1 hour, 30 minutes, 45 seconds
+/// 
+/// # Arguments
+/// 
+/// * `s` - The duration string to parse
+/// 
+/// # Returns
+/// 
+/// Returns a `time::Duration` on success, or an error string if format is invalid
 fn parse_duration(s: &str) -> Result<time::Duration, String> {
     let parts = s
         .split_terminator(':')

src/cli.rs

@@ -3,22 +3,61 @@ use obws::Client;
 use std::time::Duration;
 use tokio::time::timeout;
 
+/// Configuration for OBS WebSocket connection attempts.
+/// 
+/// This struct defines how connection attempts should be handled,
+/// including timeouts, retry limits, and delays between attempts.
 pub struct ConnectionConfig {
+    /// Maximum duration to wait for a single connection attempt
     pub timeout_duration: Duration,
+    /// Maximum number of connection attempts before giving up
     pub max_retries: u32,
+    /// Duration to wait between retry attempts
     pub retry_delay: Duration,
 }
 
 impl Default for ConnectionConfig {
     fn default() -> Self {
         Self {
+            // 10 second timeout for each connection attempt
             timeout_duration: Duration::from_secs(10),
+            // Try up to 3 times before giving up
             max_retries: 3,
+            // Wait 2 seconds between retry attempts
             retry_delay: Duration::from_secs(2),
         }
     }
 }
 
+/// Establishes a WebSocket connection to OBS with retry logic.
+/// 
+/// This function attempts to connect to an OBS WebSocket server with the
+/// provided configuration. It will retry connection attempts according to
+/// the specified config and provide detailed error feedback.
+/// 
+/// # Arguments
+/// 
+/// * `hostname` - The OBS WebSocket server hostname or IP address
+/// * `port` - The port number where OBS WebSocket is listening
+/// * `password` - Optional password for OBS WebSocket authentication
+/// * `config` - Connection configuration including timeouts and retry settings
+/// 
+/// # Returns
+/// 
+/// Returns a connected `Client` instance on success, or an error if all
+/// connection attempts fail.
+/// 
+/// # Examples
+/// 
+/// ```rust
+/// let config = ConnectionConfig::default();
+/// let client = connect_with_retry(
+///     "localhost".to_string(),
+///     4455,
+///     Some("secret".to_string()),
+///     config
+/// ).await?;
+/// ```
 pub async fn connect_with_retry(
     hostname: String,
     port: u16,
@@ -68,6 +107,19 @@ pub async fn connect_with_retry(
     }))
 }
 
+/// Checks the health of an existing OBS WebSocket connection.
+/// 
+/// This function verifies that the connection to OBS is still active
+/// and responsive by attempting to retrieve the OBS version.
+/// 
+/// # Arguments
+/// 
+/// * `client` - The OBS WebSocket client to check
+/// 
+/// # Returns
+/// 
+/// Returns `Ok(())` if the connection is healthy, or an error if the
+/// connection is unresponsive or broken.
 pub async fn check_connection_health(client: &Client) -> Result<()> {
     timeout(Duration::from_secs(5), client.general().version())
         .await

src/connection.rs

@@ -1,61 +1,62 @@
 use thiserror::Error;
 
+/// Error types for obs-cmd operations.
+/// 
+/// This enum represents all possible errors that can occur during
+/// OBS WebSocket operations, connection handling, and command execution.
+/// Each error variant provides detailed, actionable error messages.
 #[derive(Error, Debug)]
 #[allow(clippy::result_large_err)]
 pub enum ObsCmdError {
-    #[error("WebSocket connection error: {0}")]
+    #[error("WebSocket connection failed: {0}. Ensure OBS is running with WebSocket server enabled")]
     ConnectionError(#[from] obws::error::Error),
 
-    #[error("URL parsing error: {0}")]
+    #[error("Invalid URL format: {0}. Use format: obsws://hostname:port/password")]
     UrlParseError(#[from] url::ParseError),
 
-    #[error("Environment variable error: {0}")]
+    #[error("Environment variable error: {0}. Set OBS_WEBSOCKET_URL environment variable")]
     EnvError(#[from] std::env::VarError),
 
-    #[allow(dead_code)]
-    #[error("Command execution failed: {message}")]
-    CommandError { message: String },
 
-    #[error("Invalid audio command: {command}")]
+
+    #[error("Invalid audio command '{command}'. Valid commands are: mute, unmute, toggle, status")]
     InvalidAudioCommand { command: String },
 
-    #[error("Invalid filter command: {command}")]
+    #[error("Invalid filter command '{command}'. Valid commands are: enable, disable, toggle")]
     InvalidFilterCommand { command: String },
 
-    #[error("Invalid scene item command: {command}")]
+    #[error("Invalid scene item command '{command}'. Valid commands are: enable, disable, toggle")]
     InvalidSceneItemCommand { command: String },
 
-    #[error("Monitor not available: index {index} out of range")]
+    #[error("Monitor index {index} is not available. Check available monitors with OBS")]
     MonitorNotAvailable { index: u32 },
 
-    #[error("No monitor list received from OBS")]
+    #[error("Unable to retrieve monitor list from OBS. Ensure OBS is running and WebSocket is connected")]
     NoMonitorList,
 
-    #[error("Recording is not active")]
+    #[error("Recording is not currently active. Start recording first")]
     RecordingNotActive,
 
-    #[error("Recording is paused")]
+    #[error("Recording is currently paused. Use resume command to continue")]
     RecordingPaused,
 
-    #[error("No last replay found")]
+    #[error("No replay buffer recording found. Start replay buffer first")]
     NoLastReplay,
 
-    #[allow(dead_code)]
-    #[error("OBS operation failed: {0}")]
-    ObsOperationError(String),
 
-    #[allow(dead_code)]
-    #[error("Invalid URL format: {0}")]
-    InvalidUrlFormat(String),
 
-    #[error("Connection timeout after {timeout} seconds")]
+    #[error("Connection timed out after {timeout} seconds. Check OBS is running and WebSocket is enabled")]
     ConnectionTimeout { timeout: u64 },
 
-    #[error("All {attempts} connection attempts failed")]
+    #[error("Failed to connect after {attempts} attempts. Verify OBS WebSocket settings and network connectivity")]
     AllConnectionAttemptsFailed { attempts: u32 },
 
-    #[error("WebSocket URL parsing failed: {0}")]
+    #[error("Invalid WebSocket URL format: {0}. Expected format: obsws://hostname:port/password")]
     WebSocketUrlParseError(String),
 }
 
+/// Result type alias for obs-cmd operations.
+/// 
+/// This is a convenience alias for `std::result::Result<T, ObsCmdError>`
+/// to simplify error handling throughout the application.
 pub type Result<T> = std::result::Result<T, ObsCmdError>;