docs(args): 中文注释 src/args.rs CLI 参数定义

src/args.rs

@@ -1,35 +1,75 @@
+//! CLI 参数定义模块（基于 `clap` derive 宏）。
+//!
+//! 本文件用 `clap` 的 derive 宏把一个普通 struct 变成命令行解析器，思路类
+//! 似 Go 的 `flag` 包，但更贴近"struct tag 自动生成"——每个 `pub` 字段配
+//! 一行 `#[arg(...)]` 属性宏，clap 在编译期据此生成 `-x` / `--xxx` 选项、
+//! 帮助文案、默认值和类型校验。`#[derive(Parser, Debug, Clone)]` 三个
+//! derive 的作用：
+//!   - `Parser`：clap 的入口 trait，提供 `Args::parse()`，等价于 Go 里的
+//!     `flag.Parse()`；
+//!   - `Debug`：支持 `{:?}` 调试打印；
+//!   - `Clone`：允许 `Args::clone()` 值复制（运行循环里会用到）。
+//!
+//! Rust ↔ Go 类型对照（本文件用到的）：
+//!   - `Option<String>` ≈ Go `*string`：`None` 表示用户没传该 flag，等价于
+//!     `nil` 指针；`Some(s)` 表示传了；
+//!   - `String`（无 `Option`）≈ Go `string`：必有值，由 `default_value`
+//!     兜底，所以运行期不会空；
+//!   - `u32` / `u64` / `u16` ≈ Go `uint32` / `uint64` / `uint16`；
+//!   - `bool` ≈ Go `bool`，但 clap 把它当开关：出现即 `true`，不出现即
+//!     `false`，等价于 Go 里没有参数的 `flag.Bool`；
+//!   - `default_value_t = 30` ≈ Go `flag.Int("fps", 30, "...")` 的第二个
+//!     参数（默认值）；
+//!   - `default_value = "h264"` 用于 `String` 字段，等价意思；
+//!   - `#[arg(short, long)]` 同时生成短选项（`-o`，取字段首字母）和长选项
+//!     （`--output`）；
+//!   - `#[arg(long)]` 只生成长选项 `--output-name`，没有短形式。
+//!
+//! 注意：`AGENTS.md` 明确指出 README 的 CLI 表对 `--backend` 和 `--no-persist`
+//! 已过时，**以本文件为准**。
+
 use clap::Parser;
 
+// 根解析器 struct。下方 `#[command(...)]` 设置 `--help` 第一行的程序名和
+// `about` 文案；注意不要在此 struct 上加 `///`，否则 clap 会把 doc 注释
+// 注入 help 文案，可能覆盖 `about`，导致 byte-identical 不变量被破坏。
 #[derive(Parser, Debug, Clone)]
 #[command(name = "wl-webrtc", about = "Wayland screen capture and encoding tool")]
 pub struct Args {
     /// Output file path (e.g., output.mp4, output.mkv). Optional when using --port for WebRTC mode
     #[arg(short, long)]
     pub output: Option<String>,
+    // 输出文件路径（`-o`/`--output`）。`Option<String>` ≈ Go `*string`，`None` 表示用户没传
 
     /// Wayland output name to capture
     #[arg(long)]
     pub output_name: Option<String>,
+    // 指定要抓取的 Wayland 输出（显示器）名；`None` 时由后端自动选主屏
 
     /// Target frames per second
     #[arg(long, default_value_t = 30)]
     pub fps: u32,
+    // 目标帧率（`--fps`，默认 30）。`default_value_t = 30` ≈ Go `flag.Int("fps", 30, ...)`
 
     /// Video codec (h264 only for MVP)
     #[arg(long, default_value = "h264")]
     pub codec: String,
+    // 视频编码器（`--codec`，默认 `h264`）。MVP 阶段只支持 H.264，对比 Go 里 owned 的 `string`
 
     /// Hardware acceleration method (vaapi only for MVP)
     #[arg(long, default_value = "vaapi")]
     pub hw_accel: String,
+    // 硬件加速方式（`--hw-accel`，默认 `vaapi`），目前只接受 `vaapi`
 
     /// DRM render device path (e.g., /dev/dri/renderD128)
     #[arg(long)]
     pub drm_device: Option<String>,
+    // DRM 渲染节点路径（如 `/dev/dri/renderD128`），VAAPI 上下文需要它；`None` 时自动探测
 
     /// Target bitrate in bits per second
     #[arg(long)]
     pub bitrate: Option<u64>,
+    // 目标码率（bps）。`Option<u64>` ≈ Go `*uint64`，`None` 时编码器用内部默认码率
 
     /// Maximum bitrate in bps for WebRTC mode. Caps BWE-driven escalation to
     /// prevent large IDR bursts from swamping the network. Default 8 Mbps covers
@@ -37,28 +77,35 @@ pub struct Args {
     /// See issue #23.
     #[arg(long, default_value = "8000000")]
     pub max_bitrate: u64,
+    // WebRTC 模式下的码率上限（默认 8 Mbps），抑制 IDR 突发造成网络拥塞；MP4 模式忽略
 
     /// Group of Pictures (GOP) size
     #[arg(long)]
     pub gop_size: Option<u32>,
+    // GOP 长度（关键帧间距）；`None` 时由编码器按内部策略自选
 
     /// Enable verbose logging
     #[arg(short, long)]
     pub verbose: bool,
+    // 详细日志（`-v`/`--verbose`）。`bool` 在 clap 里是开关：出现即 `true`，等价 Go `flag.Bool`
 
     /// Capture backend to use: 'screencopy' (wlroots) or 'portal' (KWin/KDE). Auto-detected if omitted
     #[arg(long)]
     pub backend: Option<String>,
+    // 抓屏后端（`screencopy` 或 `portal`）；`None` 时由 `backend_detect.rs` 自动选择
 
     /// Port for WebRTC HTTP signaling server; 0 keeps MP4 file output mode
     #[arg(long, default_value_t = 0)]
     pub port: u16,
+    // WebRTC HTTP 信令端口（`--port`，默认 0）。`0` 走 MP4 文件输出模式，`>0` 走 WebRTC 模式
 
     /// Force re-authorization dialog (ignore saved portal restore token)
     #[arg(long)]
     pub no_persist: bool,
+    // 忽略已保存的 portal restore token，强制每次都弹授权对话框（测试时常用）
 
     /// Enable per-second pipeline statistics output for stutter diagnosis
     #[arg(long)]
     pub stats: bool,
+    // 每秒打印管线统计（编码帧数、延迟等），用于卡顿诊断
 }