From 6b48a5409148fb7567dd4640ceacbdcb2989ebdc Mon Sep 17 00:00:00 2001
From: Eric Kaden <608341+EricKaden@users.noreply.github.com>
Date: Thu, 22 Oct 2026 03:23:30 -0400
Subject: [PATCH] M6: doc comments on the functions next to the
 runtimeHighlight change

---
 crates/engine/src/tests.rs           | 2 ++
 crates/engine/src/xfa.rs             | 2 ++
 crates/js/src/tests.rs               | 5 +++++
 crates/js/src/xfa.rs                 | 2 ++
 crates/ui-egui/tests/ui_group/xfa.rs | 2 ++
 5 files changed, 13 insertions(+)

diff --git a/crates/engine/src/tests.rs b/crates/engine/src/tests.rs
index 93f9855416..69774465b4 100644
--- a/crates/engine/src/tests.rs
+++ b/crates/engine/src/tests.rs
@@ -7016,6 +7016,8 @@ fn dynamic_calculation_reads_and_side_effects_reach_later_fields() {
     assert!(s.take_js_output(id).errors.is_empty());
 }
 
+/// Within one edit, a field's `display` reads as the file had it before the edit, even after a
+/// script set it with the value cached; the next edit's runner reads what the script wrote.
 #[test]
 fn scripted_display_changes_survive_warm_cache_and_new_edit() {
     use pdfcraft_forms::{FieldEvent, Scripts};
diff --git a/crates/engine/src/xfa.rs b/crates/engine/src/xfa.rs
index d9a3e04736..24174add44 100644
--- a/crates/engine/src/xfa.rs
+++ b/crates/engine/src/xfa.rs
@@ -164,6 +164,8 @@ fn is_field(n: &FormNode, som: &str, depth: usize) -> bool {
     (n.som == som && n.kind == Some(NodeKind::Field)) || n.children.iter().any(|c| is_field(c, som, depth + 1))
 }
 
+/// The subform or other container at SOM path `som` in the live form under `n` (fields are
+/// skipped), searched at most 64 levels deep.
 fn find_container<'a>(n: &'a FormNode, som: &str, depth: usize) -> Option<&'a FormNode> {
     if depth > 64 {
         return None;
diff --git a/crates/js/src/tests.rs b/crates/js/src/tests.rs
index 2f26e7cba5..bd12007a6a 100644
--- a/crates/js/src/tests.rs
+++ b/crates/js/src/tests.rs
@@ -1,5 +1,7 @@
 use super::*;
 
+/// The AcroForm fields these tests' scripts read and write: prices, a quantity, a total, a ZIP
+/// code, a check box and a drop-down with shown and saved items.
 fn fields() -> Vec<FieldState> {
     let mut agree = FieldState::new("agree", FieldType::CheckBox, vec![]);
     agree.options = vec![("Yes".into(), "Yes".into())];
@@ -20,6 +22,7 @@ fn doc() -> DocInfo {
     DocInfo { file_name: "order.pdf".into(), num_pages: 3, page: 0, info: vec![("title".into(), "Order".into())], highlight: false }
 }
 
+/// Run AcroForm JavaScript `script` for `event` on these tests' document and fields.
 fn go(script: &str, event: &Event) -> Outcome {
     run(script, event, &doc(), &fields(), &[], Limits::default())
 }
@@ -1212,6 +1215,8 @@ mod session {
     }
 }
 
+/// Scripts run on a shared field snapshot without changing it: a script's writes and a failed
+/// script's partial writes stay in its own result, and its globals don't reach the next script.
 #[test]
 fn shared_field_snapshots_isolate_writes_errors_and_script_globals() {
     let initial = Arc::new(fields());
diff --git a/crates/js/src/xfa.rs b/crates/js/src/xfa.rs
index beabdcdc03..0c59115345 100644
--- a/crates/js/src/xfa.rs
+++ b/crates/js/src/xfa.rs
@@ -1015,6 +1015,7 @@ fn resolver(ctx: &mut Context, from: usize, many: bool) -> JsResult<JsValue> {
 
 // ── xfa.host, xfa.layout, xfa.event, app, console ───────────────────────────────────────────
 
+/// Queue effect `e` (a value set, a message, a request) for the engine to apply after the script.
 fn effect(ctx: &mut Context, e: XfaEffect) -> JsResult<()> {
     host(ctx)?.borrow_mut().push(e);
     Ok(())
@@ -1036,6 +1037,7 @@ fn set_runtime_highlight(_: &JsValue, args: &[JsValue], ctx: &mut Context) -> Js
     Ok(JsValue::undefined())
 }
 
+/// `xfa.host.messageBox(text)`: queues the message (cut to the stored length) and answers 1 (OK).
 fn message_box(_: &JsValue, args: &[JsValue], ctx: &mut Context) -> JsResult<JsValue> {
     let m = clip(text(&arg(args, 0), ctx)?);
     effect(ctx, XfaEffect::MessageBox(m))?;
diff --git a/crates/ui-egui/tests/ui_group/xfa.rs b/crates/ui-egui/tests/ui_group/xfa.rs
index 643bc3903d..c3a9a2cdd8 100644
--- a/crates/ui-egui/tests/ui_group/xfa.rs
+++ b/crates/ui-egui/tests/ui_group/xfa.rs
@@ -213,6 +213,8 @@ fn scripts_turned_off_by_a_click_bring_a_closed_notice_bar_back() {
     assert!(!says_scripts_are_off(&h.state().toast), "{:?}", h.state().toast);
 }
 
+/// On an encrypted dynamic XFA form that allows filling, the notice bar shows the layout note and
+/// the security sentence together, with both the field-highlight and Security settings buttons.
 #[test]
 fn a_secured_dynamic_xfa_form_shows_its_layout_and_its_security() {
     // Changing and assembling withheld, filling allowed.