M12: docstrings for the helpers the focus-script change touches

crates/automation/src/a11y.rs

@@ -684,6 +684,8 @@ impl Automation {
         self.js_document_scripts(a)
     }
 
+    /// `form_set_script`: set field `field`'s JavaScript for `event` to `script`, or remove it when
+    /// `script` is left out, as one undoable edit; returns the console output and errors.
     pub(crate) fn form_set_script(&mut self, a: &Args) -> Result<Value> {
         let edit = pdfcraft_engine::Edit::SetFieldScript {
             name: a.str("field")?.into(),

crates/engine/src/lib.rs

@@ -2409,6 +2409,8 @@ struct EditCtx {
 }
 
 impl EditCtx {
+    /// The context for one edit made at `now` (Unix seconds, when known), its random values
+    /// seeded from the time and `salt`.
     fn new(now: Option<i64>, salt: u64) -> Self {
         let mut seed = 0x9E37_79B9_7F4A_7C15u64 ^ salt;
         if let Some(t) = now {
@@ -3922,6 +3924,8 @@ impl Session {
                     .map_err(EditError::Write)?;
                 cx.xfa_out.errors.extend(notes);
             }
+            /// The fields edit `e` (and the edits it batches) gives new values, and whether it
+            /// resets the form.
             fn collect(e: &Edit, changed: &mut Vec<String>, reset: &mut bool) {
                 match e {
                     Edit::SetFieldValue { name, .. } => changed.push(name.clone()),

crates/xfa/src/script.rs

@@ -446,6 +446,7 @@ pub fn has_scripts(tpl: &Template) -> bool {
     fn field(f: &Field) -> bool {
         any(&f.scripts) || [&f.calculate, &f.validate].into_iter().flatten().any(|s| !s.text.trim().is_empty())
     }
+    /// Has any object among `nodes` (and their containers, `depth` levels down) a script?
     fn walk(nodes: &[Node], depth: usize) -> bool {
         depth <= MAX_DEPTH
             && nodes.iter().any(|n| match n {