From aa06343e7927318e7e8cfffd4d5a741ec5c5cce7 Mon Sep 17 00:00:00 2001
From: Jonathan Kew <jfkthame@gmail.com>
Date: Mon, 4 Mar 2024 10:02:52 +0000
Subject: [PATCH] Add comments re level-run processing.

---
 src/explicit.rs |  9 +++++++--
 src/lib.rs      | 31 +++++++++++++++++++++++++++++++
 src/prepare.rs  |  2 +-
 3 files changed, 39 insertions(+), 3 deletions(-)

diff --git a/src/explicit.rs b/src/explicit.rs
index 3da6d96..5760ab8 100644
--- a/src/explicit.rs
+++ b/src/explicit.rs
@@ -23,7 +23,8 @@ use super::prepare::removed_by_x9;
 use super::LevelRunVec;
 use super::TextSource;
 
-/// Compute explicit embedding levels for one paragraph of text (X1-X8).
+/// Compute explicit embedding levels for one paragraph of text (X1-X8), and identify
+/// level runs (BD7) for use when determining Isolating Run Sequences (X10).
 ///
 /// `processing_classes[i]` must contain the `BidiClass` of the char at byte index `i`,
 /// for each char in `text`.
@@ -191,10 +192,13 @@ pub fn compute<'a, T: TextSource<'a> + ?Sized>(
             processing_classes[i + j] = processing_classes[i];
         }
 
-        // Check if we need to start a new level run.
+        // Identify level runs to be passed to prepare::isolating_run_sequences().
         if i == 0 {
+            // Initialize for the first (or only) run.
             current_run_level = levels[i];
         } else {
+            // Check if we need to start a new level run.
+            // <https://www.unicode.org/reports/tr9/#BD7>
             if !removed_by_x9(original_classes[i]) && levels[i] != current_run_level {
                 // End the last run and start a new one.
                 runs.push(current_run_start..i);
@@ -204,6 +208,7 @@ pub fn compute<'a, T: TextSource<'a> + ?Sized>(
         }
     }
 
+    // Append the trailing level run, if non-empty.
     if levels.len() > current_run_start {
         runs.push(current_run_start..levels.len());
     }
diff --git a/src/lib.rs b/src/lib.rs
index 8b99ca1..4899275 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1580,6 +1580,24 @@ mod tests {
     #[cfg(feature = "hardcoded-data")]
     fn test_process_text() {
         let tests = vec![
+            (
+                // text
+                "",
+                // base level
+                Some(RTL_LEVEL),
+                // levels
+                Level::vec(&[]),
+                // original_classes
+                vec![],
+                // paragraphs
+                vec![],
+                // levels_u16
+                Level::vec(&[]),
+                // original_classes_u16
+                vec![],
+                // paragraphs_u16
+                vec![],
+            ),
             (
                 // text
                 "abc123",
@@ -1741,6 +1759,19 @@ mod tests {
                     paragraphs: t.4.clone(),
                 }
             );
+            // If it was empty, also test that ParagraphBidiInfo handles it safely.
+            if t.4.len() == 0 {
+                assert_eq!(
+                    ParagraphBidiInfo::new(t.0, t.1),
+                    ParagraphBidiInfo {
+                        text: t.0,
+                        original_classes: t.3.clone(),
+                        levels: t.2.clone(),
+                        paragraph_level: RTL_LEVEL,
+                        is_pure_ltr: true,
+                    }
+                )
+            }
             // If it was a single paragraph, also test ParagraphBidiInfo.
             if t.4.len() == 1 {
                 assert_eq!(
diff --git a/src/prepare.rs b/src/prepare.rs
index a353a16..f7b35ad 100644
--- a/src/prepare.rs
+++ b/src/prepare.rs
@@ -277,7 +277,7 @@ impl IsolatingRunSequence {
 ///
 /// <http://www.unicode.org/reports/tr9/#BD7>
 ///
-/// Only used for tests; runs are identified during explicit::compute.
+/// This is only used by tests; normally level runs are identified during explicit::compute.
 #[cfg(test)]
 fn level_runs(levels: &[Level], original_classes: &[BidiClass]) -> Vec<LevelRun> {
     assert_eq!(levels.len(), original_classes.len());