docs: 添加注释

Author: zty012

crates/project_graph/Trunk.toml

@@ -1,2 +1,3 @@
 [build]
+# Cloudflare Workers Static Assets 单个文件大小限制为 25MiB，需要压缩一下
 minify = "on_release"

crates/project_graph/src/app.rs

@@ -1,3 +1,5 @@
+//! egui 应用主入口
+
 use lucide_icons::Icon;
 
 use crate::{
@@ -36,6 +38,7 @@ impl eframe::App for MyApp {
     }
 
     fn update(&mut self, ctx: &egui::Context, _frame: &mut eframe::Frame) {
+        // 因为是手动处理绘图逻辑的，所以需要持续请求重绘
         ctx.request_repaint();
 
         egui::TopBottomPanel::top("top_panel").show(ctx, |ui| {

crates/project_graph/src/fonts.rs

@@ -1,7 +1,8 @@
+/// 为指定的 egui 上下文配置字体
 pub fn setup_custom_fonts(ctx: &egui::Context) {
     let mut fonts = egui::FontDefinitions::default();
 
-    // 默认字体
+    // 在桌面平台上尝试加载系统字体
     #[cfg(desktop)]
     {
         use font_kit::family_name::FamilyName;
@@ -33,6 +34,7 @@ pub fn setup_custom_fonts(ctx: &egui::Context) {
             }
         }
     }
+    // 在不支持使用 font-kit 的平台上，使用内置的 MiSans 字体作为替代
     #[cfg(any(wasm, android))]
     {
         // Web 平台使用内置字体
@@ -66,6 +68,15 @@ pub fn setup_custom_fonts(ctx: &egui::Context) {
 }
 
 /// 获取 Lucide 图标的 Unicode 字符串
+///
+/// # Examples
+///
+/// ```
+/// # use lucide_icons::Icon;
+/// # use project_graph::fonts::ic;
+/// let settings_icon = ic(Icon::Settings);
+/// assert_eq!(settings_icon, "\u{e154}");
+/// ```
 pub fn ic(icon: lucide_icons::Icon) -> String {
     char::from(icon).to_string()
 }

crates/project_graph/src/lib.rs

@@ -1,3 +1,7 @@
+//! # Project Graph
+//!
+//! 无限画布上的思维操作系统。融合笔记、思维导图与系统分析，用图论拓扑重构你的知识网络。
+
 pub mod app;
 pub mod fonts;
 pub mod settings;
@@ -7,6 +11,8 @@ pub mod stage;
 pub mod structs;
 pub mod themes;
 
+/// Android 平台入口点
+/// 将会编译为 libproject_graph.so，作为一个 Native Activity
 #[cfg(android)]
 #[unsafe(no_mangle)]
 fn android_main(app: android_activity::AndroidApp) {

crates/project_graph/src/main.rs

@@ -1,3 +1,4 @@
+/// 桌面平台入口点
 #[cfg(desktop)]
 fn main() {
     env_logger::init();
@@ -16,6 +17,7 @@ fn main() {
     .expect("Failed to start eframe");
 }
 
+/// WebAssembly 平台入口点
 #[cfg(wasm)]
 fn main() {
     use eframe::wasm_bindgen::JsCast;

crates/project_graph/src/smooth_value.rs

@@ -1,4 +1,19 @@
-/// 数据结构，用于实现缓动效果
+/// 一个支持缓动过渡的值容器，适用于需要平滑动画效果的场景。
+///
+/// # Examples
+///
+/// ```
+/// # use project_graph::smooth_value::SmoothValue;
+/// let mut smooth = SmoothValue::new(0.0).with_speed(5.0);
+/// smooth.set(10.0);
+/// // 模拟每帧更新，假设每帧间隔为 0.032 秒（约 30 FPS）
+/// for _ in 0..100 {
+///     smooth.tick(0.032);
+///     println!("Current value: {}", smooth.get());
+/// }
+/// // 最终值应该接近目标值
+/// assert!((smooth.get() - 10.0).abs() < 0.01);
+/// ```
 pub struct SmoothValue<T> {
     current: T,
     target: T,
@@ -20,11 +35,15 @@ where
             speed: 10.0,
         }
     }
+    /// 指数衰减速率系数
+    /// 物体完成约 63.2% 的过渡所需的时间为 1/speed 秒
+    /// 较高的值会更快地接近目标值，但可能会产生更明显的动画跳跃
     pub fn with_speed(mut self, speed: f32) -> Self {
         self.speed = speed;
         self
     }
 
+    /// 更新当前值，应该在每帧调用，dt 是与上一帧的时间间隔（秒）
     pub fn tick(&mut self, dt: f32) {
         let lerp_factor = (1.0 - (-self.speed * dt).exp()).clamp(0.0, 1.0);
 

crates/project_graph/src/stage.rs

@@ -2,13 +2,13 @@ mod camera;
 
 use camera::Camera;
 use eframe::egui::{self};
-use egui::{Pos2, Vec2};
+use egui::Pos2;
 use nanoid::nanoid;
 use rand::Rng;
 
 use crate::structs::{StageObject, TextNode};
 
-/// egui和画布之间的桥梁
+/// egui 和画布之间的桥梁
 /// 负责坐标系转换、事件处理等
 pub struct Stage {
     camera: Camera,

crates/project_graph/src/themes.rs

@@ -3,6 +3,7 @@ use egui::{
     style::{WidgetVisuals, Widgets},
 };
 
+/// 将主题应用到指定的 egui 上下文上
 pub fn apply_custom_theme(ctx: &Context) {
     let mut style = (*ctx.style()).clone();