From 66e369de26e33b46fe731315046692704bde62dc Mon Sep 17 00:00:00 2001
From: Katacc <katacc@iostria.org>
Date: Wed, 21 Oct 2026 17:01:37 +0300
Subject: [PATCH] Doc comments for the language functions

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 crates/engine/src/cmd/format.rs | 5 ++++-
 crates/engine/src/tests.rs      | 2 ++
 2 files changed, 6 insertions(+), 1 deletion(-)

diff --git a/crates/engine/src/cmd/format.rs b/crates/engine/src/cmd/format.rs
index 60771796..086821cf 100644
--- a/crates/engine/src/cmd/format.rs
+++ b/crates/engine/src/cmd/format.rs
@@ -427,6 +427,7 @@ fn language_edit(id: &str, p: &Value) -> Result<impl Fn(&mut RunProps) + Send +
         }
     })
 }
+/// Review › Language on the selected text (or the selected shapes' text).
 fn language(s: &mut Session, p: &Value) -> Result<Value> {
     let f = language_edit("format.language", p)?;
     format_run(s, &f)
@@ -434,11 +435,12 @@ fn language(s: &mut Session, p: &Value) -> Result<Value> {
 /// Every run in the deck, and the text styles new text inherits from, in one language.
 fn language_all(s: &mut Session, p: &Value) -> Result<Value> {
     let f = language_edit("format.languageAll", p)?;
-    // Runs, end marks and the body's own list style levels (never creating one).
+    /// Runs, end marks and the body's own list style levels (never creating one).
     fn body(t: &mut deckcraft_model::text::TextBody, f: &dyn Fn(&mut RunProps)) {
         ed::format_all(t, f);
         t.list_style.levels.iter_mut().flatten().for_each(|lv| f(&mut lv.run));
     }
+    /// Every text body in `list`: shapes, table cells and groups (nested at most 64 deep).
     fn shapes(list: &mut [Shape], f: &dyn Fn(&mut RunProps), depth: usize) {
         if depth > 64 {
             return;
@@ -454,6 +456,7 @@ fn language_all(s: &mut Session, p: &Value) -> Result<Value> {
             }
         }
     }
+    /// A master or presentation text style's levels: what new text inherits.
     fn styles(l: &mut deckcraft_model::text::ListStyle, f: &dyn Fn(&mut RunProps)) {
         // Level 1 always, so a deck without a default text style gets one.
         if l.level(0).is_none() {
diff --git a/crates/engine/src/tests.rs b/crates/engine/src/tests.rs
index 53e45025..6d9a0ffe 100644
--- a/crates/engine/src/tests.rs
+++ b/crates/engine/src/tests.rs
@@ -3756,6 +3756,8 @@ fn language_marks_text_and_no_proof_and_repeats_are_reported() {
     assert!(s.execute("format.language", &json!({"lang": "en US!"})).is_err());
 }
 
+/// Review › Language › Whole presentation: every run, placeholder list style and default text style
+/// takes the language, with nothing selected, in one undo step.
 #[test]
 fn language_all_marks_every_text_in_the_deck_with_nothing_selected() {
     crate::spell::install("xx-AL", crate::spell::Dictionary::parse(b"", b"2\nhello\nworld\n"));