chore: cleanup comments

Author: ra0x3

src/charting/rasciigraph.rs

@@ -6,9 +6,13 @@ use std::vec::Vec;
 /// Configuration for ASCII graph plotting
 #[derive(Default)]
 pub struct Config {
+    /// Width of the graph for data point interpolation.
     width: u32,
+    /// Height of the graph in terminal rows.
     height: u32,
+    /// Offset for Y-axis labels from the left edge.
     offset: u32,
+    /// Caption text displayed below the graph.
     caption: String,
     /// Number of decimal places for Y-axis labels
     y_precision: Option<i32>,

src/cli.rs

@@ -10,7 +10,7 @@ use tracing::level_filters::LevelFilter;
 pub struct LogLevelArg(LevelFilter);
 
 impl LogLevelArg {
-    /// String representation suitable for `RUST_LOG`.
+    /// Returns the string representation suitable for `RUST_LOG`.
     pub fn as_str(&self) -> &'static str {
         match self.0 {
             LevelFilter::OFF => "off",
@@ -79,7 +79,7 @@ pub enum LogKind {
 }
 
 impl LogKind {
-    /// String representation for file paths and display.
+    /// Returns the string representation for file paths and display.
     pub fn as_str(&self) -> &'static str {
         match self {
             LogKind::Stdout => "stdout",

src/constants.rs

@@ -5,10 +5,6 @@
 
 use std::{cmp::Ordering, str::FromStr, time::Duration};
 
-// ============================================================================
-// Lock Management and Ordering
-// ============================================================================
-
 /// Typed lock abstraction for enforcing proper lock acquisition order in the daemon.
 ///
 /// This enum ensures that locks are always acquired in a consistent order to prevent
@@ -100,10 +96,6 @@ impl Ord for DaemonLock {
     }
 }
 
-// ============================================================================
-// File System Constants
-// ============================================================================
-
 /// Name of the PID file stored in the state directory.
 /// Contains mappings of service names to process IDs.
 pub const PID_FILE_NAME: &str = "pid.xml";
@@ -115,20 +107,12 @@ pub const PID_LOCK_SUFFIX: &str = ".lock";
 /// Contains the current state and metadata for all managed services.
 pub const STATE_FILE_NAME: &str = "state.xml";
 
-// ============================================================================
-// Shell Execution Constants
-// ============================================================================
-
 /// Default shell used for executing service commands and hooks.
 pub const DEFAULT_SHELL: &str = "sh";
 
 /// Shell argument flag for executing command strings.
 pub const SHELL_COMMAND_FLAG: &str = "-c";
 
-// ============================================================================
-// Process Management Timing
-// ============================================================================
-
 /// Number of checks to perform when waiting for a process to become ready.
 /// Used in conjunction with PROCESS_CHECK_INTERVAL.
 pub const PROCESS_READY_CHECKS: usize = 10;
@@ -149,33 +133,17 @@ pub const POST_RESTART_VERIFY_ATTEMPTS: usize = 2;
 /// Delay between post-restart verification attempts.
 pub const POST_RESTART_VERIFY_DELAY: Duration = Duration::from_millis(200);
 
-// ============================================================================
-// Logging and Output Constants
-// ============================================================================
-
 /// Maximum number of log lines to display in status output.
 /// Prevents overwhelming the terminal with excessive log data.
 pub const MAX_STATUS_LOG_LINES: usize = 50;
 
 /// Buffer size for log output streams (stdout/stderr).
 pub const LOG_BUFFER_SIZE: usize = 8192;
 
-// ============================================================================
-// Hook Execution Constants
-// ============================================================================
-
 /// Format string for hook labels combining stage and outcome.
 /// Example: "pre_start.pending", "post_start.success"
 pub const HOOK_LABEL_FORMAT: &str = "{}.{}";
 
-// ============================================================================
-// Linux-specific Constants
-// ============================================================================
-
-// ============================================================================
-// Error Messages and Formats
-// ============================================================================
-
 /// Error message for malformed environment file lines.
 pub const ENV_FILE_MALFORMED_MSG: &str =
     "Ignoring malformed line in env file for '{}': {}";
@@ -195,10 +163,6 @@ pub const INSUFFICIENT_SIGNAL_PERMISSIONS_MSG: &str =
 pub const PROCESS_TREE_TERM_FAILURE_MSG: &str =
     "Failed to terminate process tree rooted at PID {} for '{}'";
 
-// ============================================================================
-// Service Management Constants
-// ============================================================================
-
 /// Deployment strategies for service restarts.
 ///
 /// This enum provides type-safe handling of deployment strategies, ensuring

src/metrics/mod.rs

@@ -31,31 +31,47 @@ const DEFAULT_MAX_MEMORY_BYTES: usize = 10 * 1024 * 1024;
 /// Sample collected for a managed unit at a specific timestamp.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct MetricSample {
+    /// Timestamp when this sample was collected.
     pub timestamp: DateTime<Utc>,
+    /// CPU usage percentage (0-100+ for multi-core).
     pub cpu_percent: f32,
+    /// Resident set size in bytes.
     pub rss_bytes: u64,
+    /// Total bytes read from disk.
     pub io_read_bytes: u64,
+    /// Total bytes written to disk.
     pub io_write_bytes: u64,
+    /// Total bytes received from network.
     pub net_rx_bytes: u64,
+    /// Total bytes transmitted to network.
     pub net_tx_bytes: u64,
 }
 
 /// Summary statistics derived from recent samples.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct MetricsSummary {
+    /// Most recent CPU usage percentage.
     pub latest_cpu_percent: f32,
+    /// Average CPU usage across all samples.
     pub average_cpu_percent: f32,
+    /// Maximum CPU usage observed.
     pub max_cpu_percent: f32,
+    /// Most recent resident set size in bytes.
     pub latest_rss_bytes: u64,
+    /// Total number of samples used for statistics.
     pub samples: usize,
 }
 
 /// Configuration for runtime metrics collection.
 #[derive(Debug, Clone)]
 pub struct MetricsSettings {
+    /// How long to retain metrics in memory.
     pub retention: Duration,
+    /// Interval between metric samples.
     pub sample_interval: Duration,
+    /// Maximum memory used for metrics storage.
     pub max_memory_bytes: usize,
+    /// Optional spillover configuration for disk persistence.
     pub spillover: Option<SpilloverSettings>,
 }
 
@@ -73,17 +89,24 @@ impl Default for MetricsSettings {
 /// Spillover configuration used to persist evicted samples to disk.
 #[derive(Debug, Clone)]
 pub struct SpilloverSettings {
+    /// Directory where spillover segments are written.
     pub directory: PathBuf,
+    /// Maximum total bytes allowed for spillover storage.
     pub max_bytes: u64,
+    /// Target size for individual spillover segment files.
     pub segment_bytes: u64,
 }
 
+/// Errors that can occur during metrics operations.
 #[derive(Debug, Error)]
 pub enum MetricsError {
+    /// Failed to create spillover directory.
     #[error("failed to create spillover directory: {0}")]
     CreateDir(std::io::Error),
+    /// Failed to write spillover segment to disk.
     #[error("failed to write spillover segment: {0}")]
     SpilloverWrite(std::io::Error),
+    /// Failed to serialize spillover record.
     #[error("failed to serialise spillover record: {0}")]
     SpilloverSerialize(serde_json::Error),
 }
@@ -440,21 +463,26 @@ struct SpilloverRecord<'a> {
     sample: &'a MetricSample,
 }
 
+/// Creates a new shared, thread-safe metrics store with the given settings.
 pub fn shared_store(settings: MetricsSettings) -> Result<MetricsHandle, MetricsError> {
     Ok(Arc::new(RwLock::new(MetricsStore::new(settings)?)))
 }
 
 /// Unit metadata used by the collector to emit samples.
 #[derive(Debug)]
 pub struct UnitTarget {
+    /// Unique hash identifying the unit.
     pub hash: String,
+    /// Process ID if the unit has a running process.
     pub pid: Option<u32>,
 }
 
 /// Result of sampling a unit in the collector.
 #[derive(Debug)]
 pub struct CollectedSample {
+    /// Hash of the unit that was sampled.
     pub hash: String,
+    /// Collected metric sample data.
     pub sample: MetricSample,
 }
 

src/status/mod.rs

@@ -75,27 +75,37 @@ pub enum StatusError {
 #[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
 #[serde(rename_all = "snake_case")]
 pub enum OverallHealth {
+    /// All services are running as expected.
     Healthy,
+    /// Some services are not functioning properly, but system is operational.
     Degraded,
+    /// Critical services are failing, system health is compromised.
     Failing,
 }
 
 /// Describes what type of unit is represented by a status entry.
 #[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
 #[serde(rename_all = "snake_case")]
 pub enum UnitKind {
+    /// Regular service managed by the supervisor.
     Service,
+    /// Cron-scheduled job that runs at specified intervals.
     Cron,
+    /// Orphaned process from a removed or renamed service.
     Orphaned,
 }
 
 /// Health classification for a specific unit.
 #[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
 #[serde(rename_all = "snake_case")]
 pub enum UnitHealth {
+    /// Unit is operating normally.
     Healthy,
+    /// Unit is operational but experiencing issues.
     Degraded,
+    /// Unit is not functioning properly.
     Failing,
+    /// Unit is currently inactive or stopped.
     Inactive,
 }
 
@@ -1283,12 +1293,16 @@ pub fn format_elapsed(total_seconds: u64) -> String {
     }
 }
 
+/// Represents the state of a process in the system.
 #[cfg_attr(not(target_os = "linux"), allow(dead_code))]
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(rename_all = "snake_case")]
 pub enum ProcessState {
+    /// Process is currently running.
     Running,
+    /// Process has terminated but not been reaped by its parent.
     Zombie,
+    /// Process is not found in the process table.
     Missing,
 }
 

src/test_utils.rs

@@ -5,6 +5,10 @@ use std::sync::{Mutex, OnceLock};
 /// to prevent race conditions between parallel test executions.
 pub static ENV_LOCK: OnceLock<Mutex<()>> = OnceLock::new();
 
+/// Acquires the global environment lock for safe environment variable modifications in tests.
+///
+/// This function should be called by any test that modifies environment variables
+/// to prevent race conditions in parallel test execution.
 pub fn env_lock() -> std::sync::MutexGuard<'static, ()> {
     ENV_LOCK
         .get_or_init(|| Mutex::new(()))