From de88e084e6a673f2ee19f5b341088a3a0791f461 Mon Sep 17 00:00:00 2001
From: onlykshitij <30444410+onlykshitij@users.noreply.github.com>
Date: Sat, 24 Oct 2026 20:32:47 +0530
Subject: [PATCH] Scripts: doc comments for the functions this change touches

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/engine/src/commands/scripts.rs | 7 +++++++
 crates/engine/src/config.rs           | 4 ++++
 crates/ui-egui/src/native_menu.rs     | 1 +
 3 files changed, 12 insertions(+)

diff --git a/crates/engine/src/commands/scripts.rs b/crates/engine/src/commands/scripts.rs
index 01963042e..726c20c2d 100644
--- a/crates/engine/src/commands/scripts.rs
+++ b/crates/engine/src/commands/scripts.rs
@@ -122,6 +122,7 @@ pub struct ScriptEntry {
     pub source: &'static str,
 }
 
+/// Whether `name` ends in `.jsx` or `.js` (any letter case).
 fn is_script(name: &str) -> bool {
     let l = name.to_ascii_lowercase();
     l.ends_with(".jsx") || l.ends_with(".js")
@@ -230,6 +231,8 @@ fn list(s: &mut Session, _: &Value) -> Result<Value> {
     Ok(json!(scripts(s)))
 }
 
+/// `file.uninstallScript {name}`: delete an installed script or panel at the top of the Scripts
+/// folders.
 fn uninstall(s: &mut Session, p: &Value) -> Result<Value> {
     let c = "file.uninstallScript";
     let name = str_p(p, "name").ok_or_else(|| bad(c, "missing `name`"))?;
@@ -354,6 +357,7 @@ fn open_panel(s: &mut Session, p: &Value) -> Result<Value> {
     Ok(json!({"window": id, "result": out}))
 }
 
+/// The commands of File ▸ Scripts, ScriptUI panels and windows, and script settings.
 pub fn specs() -> Vec<CommandSpec> {
     vec![
         cmd!(
@@ -528,6 +532,7 @@ mod tests {
         }
     }
 
+    /// Bundled and ordinary script file names are accepted; paths are not.
     #[test]
     fn script_names_are_bare_file_names() {
         let more = ["..jsx", "a..b.js", "Äpfel ✓.jsx", "console.jsx", "Concert.jsx", "NULL.jsx", "COM10.jsx", "LPT.jsx"];
@@ -553,6 +558,7 @@ mod tests {
         }
     }
 
+    /// `Folder/File.jsx` is accepted; deeper, upward, absolute and `\` names are not.
     #[test]
     fn script_names_may_have_one_folder() {
         for name in ["Motion Kit/Animate.jsx", "a/b.jsx", "Äpfel/✓.js", "..jsx/x.jsx"] {
@@ -575,6 +581,7 @@ mod tests {
         std::fs::write(p, code).unwrap();
     }
 
+    /// Every script command takes `Folder/File.jsx` names and refuses names outside one folder level.
     #[test]
     fn scripts_in_a_subfolder_are_listed_run_and_opened_as_folder_and_file() {
         let (mut s, root) = session_in_tmp("folders");
diff --git a/crates/engine/src/config.rs b/crates/engine/src/config.rs
index af6a1d800..17d7c940a 100644
--- a/crates/engine/src/config.rs
+++ b/crates/engine/src/config.rs
@@ -24,7 +24,9 @@ pub trait ConfigStore: Send + Sync {
         }
         Ok(text)
     }
+    /// Write entry `name`, replacing any earlier text.
     fn write(&self, name: &str, data: &str) -> std::io::Result<()>;
+    /// Remove entry `name`; a missing entry is no error.
     fn remove(&self, name: &str) -> std::io::Result<()>;
     /// Names of the entries directly in `dir` (a `/`-separated name prefix such as `Scripts`),
     /// sorted. Stores that can't list return nothing.
@@ -112,6 +114,7 @@ impl ConfigStore for MemoryConfig {
         let Ok(m) = self.files.lock() else { return vec![] };
         m.keys().filter_map(|k| k.strip_prefix(&pre)).filter(|n| !n.is_empty() && !n.contains('/')).map(str::to_string).collect()
     }
+    /// The first name part of the keys under `dir/`.
     fn list_dirs(&self, dir: &str) -> Vec<String> {
         let pre = format!("{}/", dir.trim_end_matches('/'));
         let Ok(m) = self.files.lock() else { return vec![] };
@@ -166,6 +169,7 @@ impl ConfigStore for DirConfig {
         v.sort();
         v
     }
+    /// The folders in `dir`, following links like [`ConfigStore::list`] does for files.
     fn list_dirs(&self, dir: &str) -> Vec<String> {
         let Ok(rd) = std::fs::read_dir(self.dir.join(dir)) else { return vec![] };
         let mut v: Vec<String> = rd.flatten().filter(|e| e.path().is_dir()).map(|e| e.file_name().to_string_lossy().to_string()).collect();
diff --git a/crates/ui-egui/src/native_menu.rs b/crates/ui-egui/src/native_menu.rs
index 48a77d207..bcf37ae18 100644
--- a/crates/ui-egui/src/native_menu.rs
+++ b/crates/ui-egui/src/native_menu.rs
@@ -128,6 +128,7 @@ impl NativeMenu {
 
 /// Build the native menu spec for the app's current state.
 pub fn build(app: &EffectcraftApp) -> NativeMenu {
+    /// Append the native nodes of `nodes` to `out`; item ids start with `path`.
     fn rec(app: &EffectcraftApp, nodes: &[MenuNode], path: &str, out: &mut Vec<NativeNode>) {
         let mut services_added = false;
         for (i, n) in nodes.iter().enumerate() {