From e7accecfec53967fc5276647057fedab1e852673 Mon Sep 17 00:00:00 2001 From: dailz Date: Sun, 21 Jun 2026 11:00:29 +0800 Subject: [PATCH] chore: trim verbose docstrings on Portal timeout constants and enum Cleanup pass after Portal resilience commits (6ccb225, 68a6eec). Trimmed docstrings that restated information already obvious from the type/variant names or duplicated elsewhere: - PORTAL_SERVICE_TIMEOUT: 6 lines -> 3 lines (keep 'why 5s' rationale) - PORTAL_USER_DIALOG_TIMEOUT: 6 lines -> 2 lines (keep 'why 30s' rationale) - PortalPhaseTimeout enum: 5 lines -> 1 line (variants are self-documenting) - Service variant: 2 lines -> 1 line - TokenDependent variant: 2 lines -> 1 line Net: -15 lines of comment overhead. No behavior change. Tests: - cargo build --release: 0 new warnings (19 baseline preserved) - cargo test: 97 lib + 3 integration, 0 failed --- src/cap_portal.rs | 29 +++++++---------------------- 1 file changed, 7 insertions(+), 22 deletions(-) diff --git a/src/cap_portal.rs b/src/cap_portal.rs index 176a94b..f35456a 100644 --- a/src/cap_portal.rs +++ b/src/cap_portal.rs @@ -23,36 +23,21 @@ use tokio::runtime::Runtime; use crate::args::Args; -/// Timeout for Portal phases that do not require user interaction. -/// Applies to: Screencast proxy creation, session creation, source selection -/// (when a restore token is used), session start (token path), and PipeWire -/// remote fd acquisition. -/// -/// 5 seconds is generous for healthy xdg-desktop-portal (typically <500ms) -/// but bounded enough that a stuck service fails fast. +/// Portal phase timeout when no user interaction is expected (proxy/session +/// creation, token-path select/start, PipeWire fd). 5s is generous for +/// healthy xdg-desktop-portal (<500ms typical) but bounded for fast failure. const PORTAL_SERVICE_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(5); -/// Timeout for Portal phases that may require a user to click "Allow" in a -/// desktop dialog. Applies to: source selection and session start when NO -/// restore token is available (fresh authorization). -/// -/// 30 seconds gives the user time to find and click the dialog without -/// causing a spurious timeout failure. +/// Portal phase timeout when user must click "Allow" in desktop dialog +/// (select/start without restore token). 30s gives time to find the dialog. const PORTAL_USER_DIALOG_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(30); /// Classification of Portal phase timeouts to drive retry behavior. -/// -/// `TokenDependent` failures are eligible for a single automatic retry that -/// clears the cached restore token and re-runs the entire Portal setup with -/// fresh authorization. `Service` failures are not retried automatically -/// (the user should restart the Portal service instead). #[derive(Debug)] enum PortalPhaseTimeout { - /// Portal service unresponsive in a phase not related to restore token. - /// No automatic retry; user should restart Portal service. + /// Portal service unresponsive; not retried (user should restart service). Service, - /// Portal timed out in a token-dependent phase. Retry eligible: clear - /// cached token and try once more with fresh authorization. + /// Timed out in token-dependent phase; retried once after clearing token. TokenDependent, }