🦄 refactor: 优化格式化配置，补充部分注释

Author: apoint123

Cargo.lock

@@ -7,44 +7,53 @@ edition = "2024"
 crate-type = ["cdylib"]
 
 [dependencies]
+# N-API
 napi = { version = "3.8", features = ["tokio_rt", "napi9"] }
 napi-derive = "3.5"
 
-anyhow = "1.0"
-serde = { version = "1.0", features = ["derive"] }
-serde_json = "1.0"
+# Async Runtime
+tokio = { version = "1", features = ["full"] }
 
+# Log
 tracing = "0.1"
-tracing-subscriber = { version = "0.3", features = ["env-filter", "json"] }
 tracing-appender = "0.2"
+tracing-subscriber = { version = "0.3", features = ["env-filter", "json"] }
 
-discord-rich-presence = "1.0"
+# Error & Serialize
+anyhow = "1.0"
+serde = { version = "1.0", features = ["derive"] }
+serde_json = "1.0"
 
+# Utilities
+discord-rich-presence = "1.0"
 url = "2.5"
 
-tokio = { version = "1", features = ["full"] }
+[build-dependencies]
+napi-build = "2.3"
 
+# Windows
 [target.'cfg(target_os = "windows")'.dependencies.windows]
 version = "0.62"
 features = ["Media_Playback", "Storage_Streams"]
 
+# Linux
 [target.'cfg(target_os = "linux")'.dependencies]
 mpris-server = "0.9"
 tempfile = "3.24"
 
+# macOS
 [target.'cfg(target_os = "macos")'.dependencies]
 block2 = "0.6"
 objc2 = "0.6"
 objc2-app-kit = "0.3"
 objc2-foundation = "0.3"
 objc2-media-player = "0.3"
 
-[build-dependencies]
-napi-build = "2.3"
-
+# Clippy Lints
 [lints.clippy]
 pedantic = { level = "warn", priority = -1 }
 nursery = { level = "warn", priority = -1 }
 
 cast_possible_truncation = "allow"
 cast_precision_loss = "allow"
+doc_markdown = "allow"

native/external-media-integration/Cargo.toml

@@ -0,0 +1,6 @@
+comment_width = 100
+format_code_in_doc_comments = true
+imports_granularity = "Crate"
+imports_layout = "Vertical"
+wrap_comments = true
+group_imports = "StdExternalCrate"

native/external-media-integration/rustfmt.toml

@@ -1,16 +1,45 @@
-use std::sync::mpsc::{self, Receiver, Sender};
-use std::sync::{LazyLock, Mutex};
-use std::thread;
-use std::time::{Duration, SystemTime, UNIX_EPOCH};
+use std::{
+    sync::{
+        LazyLock,
+        Mutex,
+        mpsc::{
+            self,
+            Receiver,
+            Sender,
+        },
+    },
+    thread,
+    time::{
+        Duration,
+        SystemTime,
+        UNIX_EPOCH,
+    },
+};
 
-use discord_rich_presence::activity::{
-    Activity, ActivityType, Assets, Button, StatusDisplayType, Timestamps,
+use discord_rich_presence::{
+    DiscordIpc,
+    DiscordIpcClient,
+    activity::{
+        Activity,
+        ActivityType,
+        Assets,
+        Button,
+        StatusDisplayType,
+        Timestamps,
+    },
+};
+use tracing::{
+    debug,
+    info,
+    warn,
 };
-use discord_rich_presence::{DiscordIpc, DiscordIpcClient};
-use tracing::{debug, info, warn};
 
 use crate::model::{
-    DiscordConfigPayload, DiscordDisplayMode, MetadataPayload, PlayStatePayload, PlaybackStatus,
+    DiscordConfigPayload,
+    DiscordDisplayMode,
+    MetadataPayload,
+    PlayStatePayload,
+    PlaybackStatus,
     TimelinePayload,
 };
 

native/external-media-integration/src/discord.rs

@@ -1,10 +1,17 @@
 #![deny(missing_docs)]
 
 //! 一个 Electron 的原生插件，用于将播放信息同步到系统的媒体控件和/或 Discord RPC
-
-use napi::Result;
-use napi::bindgen_prelude::{Function, Unknown};
-use napi::threadsafe_function::UnknownReturnValue;
+//!
+//! 目前支持 Windows、Linux 和 MacOS 的媒体控件交互
+
+use napi::{
+    Result,
+    bindgen_prelude::{
+        Function,
+        Unknown,
+    },
+    threadsafe_function::UnknownReturnValue,
+};
 use napi_derive::napi;
 
 mod discord;
@@ -13,11 +20,15 @@ mod model;
 mod sys_media;
 
 use model::{
-    DiscordConfigPayload, MetadataPayload, PlayModePayload, PlayStatePayload, TimelinePayload,
+    DiscordConfigPayload,
+    MetadataParam,
+    MetadataPayload,
+    PlayModePayload,
+    PlayStatePayload,
+    SystemMediaEvent,
+    TimelinePayload,
 };
 
-use crate::model::{MetadataParam, SystemMediaEvent};
-
 /// 初始化插件
 ///
 /// ### 参数
@@ -167,7 +178,8 @@ pub fn disable_discord_rpc() {
 ///
 /// ### 参数
 ///
-/// * `payload` - 配置信息，可以配置是否在暂停后也显示 Discord Activity 和 状态显示风格。详情请查看 [`DiscordConfigPayload`]
+/// * `payload` - 配置信息，可以配置是否在暂停后也显示 Discord Activity 和 状态显示风格。详情请查看
+///   [`DiscordConfigPayload`]
 #[napi]
 pub fn update_discord_config(payload: DiscordConfigPayload) {
     discord::update_config(payload);

native/external-media-integration/src/lib.rs

@@ -1,11 +1,27 @@
-use anyhow::{Context, Result};
-use std::fs;
-use std::path::PathBuf;
-use std::sync::OnceLock;
-use tracing::{error, trace};
-use tracing_appender::non_blocking::WorkerGuard;
-use tracing_appender::rolling::RollingFileAppender;
-use tracing_subscriber::{filter::LevelFilter, fmt, layer::SubscriberExt, util::SubscriberInitExt};
+use std::{
+    fs,
+    path::PathBuf,
+    sync::OnceLock,
+};
+
+use anyhow::{
+    Context,
+    Result,
+};
+use tracing::{
+    error,
+    trace,
+};
+use tracing_appender::{
+    non_blocking::WorkerGuard,
+    rolling::RollingFileAppender,
+};
+use tracing_subscriber::{
+    filter::LevelFilter,
+    fmt,
+    layer::SubscriberExt,
+    util::SubscriberInitExt,
+};
 
 static LOG_GUARD: OnceLock<WorkerGuard> = OnceLock::new();
 

native/external-media-integration/src/logger.rs

@@ -75,7 +75,6 @@ impl fmt::Debug for MetadataPayload {
 }
 
 #[napi(object)]
-#[allow(clippy::doc_markdown)]
 pub struct MetadataParam {
     pub song_name: String,
     pub author_name: String,
@@ -99,7 +98,8 @@ pub struct MetadataParam {
 
     /// 当前歌曲时长，单位是毫秒
     ///
-    /// 用于 Linux、MacOS、Discord RPC 的元数据更新。Windows 使用 [`TimelinePayload`] 的 `total_time` 字段。
+    /// 用于 Linux、MacOS、Discord RPC 的元数据更新。Windows 使用 [`TimelinePayload`] 的
+    /// `total_time` 字段。
     pub duration: Option<f64>,
 }
 
@@ -117,6 +117,9 @@ impl From<MetadataParam> for MetadataPayload {
     }
 }
 
+// 使用 string_enum 加上 --no-const-enum 编译参数可以神奇地让 napi-rs
+// 把枚举生成为字符串联合类型，这样就可以直接从 index.d.ts 导入它们而不用再复制一份了
+
 #[napi(string_enum)]
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum PlaybackStatus {
@@ -157,9 +160,8 @@ pub struct PlayModePayload {
 
 /// Discord 显示模式枚举
 ///
-/// 控制 Discord 左下角 "正在听 XXX" 的显示内容
+/// 不打开详细信息面板时，在用户名下方显示的小字
 #[napi(string_enum)]
-#[allow(clippy::doc_markdown)]
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum DiscordDisplayMode {
     /// Listening to SPlayer
@@ -175,7 +177,10 @@ pub enum DiscordDisplayMode {
 #[derive(Debug, Clone)]
 pub struct DiscordConfigPayload {
     /// 暂停时是否显示
+    ///
+    /// 注意暂停时进度会固定为 0
     pub show_when_paused: bool,
-    /// 显示模式
+
+    /// 显示模式，参考 [`DiscordDisplayMode`]
     pub display_mode: Option<DiscordDisplayMode>,
 }

native/external-media-integration/src/model.rs

@@ -1,24 +1,56 @@
-use std::io::Write;
-use std::sync::{Arc, RwLock};
-use std::time::{SystemTime, UNIX_EPOCH};
-use std::{process, thread};
+use std::{
+    io::Write,
+    process,
+    sync::{
+        Arc,
+        RwLock,
+    },
+    thread,
+    time::{
+        SystemTime,
+        UNIX_EPOCH,
+    },
+};
 
 use anyhow::Result;
-use mpris_server::zbus::zvariant::ObjectPath;
 use mpris_server::{
-    LoopStatus as MprisLoopStatus, Metadata, PlaybackStatus as MprisPlaybackStatus, Player, Time,
+    LoopStatus as MprisLoopStatus,
+    Metadata,
+    PlaybackStatus as MprisPlaybackStatus,
+    Player,
+    Time,
+    zbus::zvariant::ObjectPath,
 };
 use napi::threadsafe_function::ThreadsafeFunctionCallMode;
 use tempfile::NamedTempFile;
-use tokio::runtime::Runtime;
-use tokio::sync::mpsc::{UnboundedReceiver, UnboundedSender, unbounded_channel};
-use tracing::{debug, error};
-
-use crate::model::{PlaybackStatus, RepeatMode, SystemMediaEventType};
+use tokio::{
+    runtime::Runtime,
+    sync::mpsc::{
+        UnboundedReceiver,
+        UnboundedSender,
+        unbounded_channel,
+    },
+};
+use tracing::{
+    debug,
+    error,
+};
 
-use super::{
-    MetadataPayload, PlayModePayload, PlayStatePayload, SystemMediaControls, SystemMediaEvent,
-    SystemMediaThreadsafeFunction, TimelinePayload,
+use crate::{
+    model::{
+        MetadataPayload,
+        PlayModePayload,
+        PlayStatePayload,
+        PlaybackStatus,
+        RepeatMode,
+        SystemMediaEvent,
+        SystemMediaEventType,
+        TimelinePayload,
+    },
+    sys_media::{
+        SystemMediaControls,
+        SystemMediaThreadsafeFunction,
+    },
 };
 
 /// 主线程和后台 D-Bus 现成通信的指令