From 9139baf263b93115bd7f6707bb6a488b883296ba Mon Sep 17 00:00:00 2001
From: PgBiel <9021226+PgBiel@users.noreply.github.com>
Date: Tue, 10 Jun 2025 01:53:43 -0300
Subject: [PATCH] improve level docs

---
 crates/typst-library/src/layout/grid/mod.rs | 9 ++++++---
 crates/typst-library/src/model/table.rs     | 9 ++++++---
 2 files changed, 12 insertions(+), 6 deletions(-)

diff --git a/crates/typst-library/src/layout/grid/mod.rs b/crates/typst-library/src/layout/grid/mod.rs
index 7ee323967..0f0dbf200 100644
--- a/crates/typst-library/src/layout/grid/mod.rs
+++ b/crates/typst-library/src/layout/grid/mod.rs
@@ -470,9 +470,12 @@ pub struct GridHeader {
 
     /// The level of the header. Must not be zero.
     ///
-    /// This is used during repetition multiple headers at once. When a header
-    /// with a lower level starts repeating, all headers with a lower level stop
-    /// repeating.
+    /// This allows repeating multiple headers at once. Headers with different
+    /// levels can repeat together, as long as they have ascending levels.
+    ///
+    /// Notably, when a level with a lower level starts repeating, all higher
+    /// or equal level headers stop repeating (they are "replaced" by the new
+    /// header).
     #[default(NonZeroU32::ONE)]
     pub level: NonZeroU32,
 
diff --git a/crates/typst-library/src/model/table.rs b/crates/typst-library/src/model/table.rs
index 14d40e749..9f4cd5a52 100644
--- a/crates/typst-library/src/model/table.rs
+++ b/crates/typst-library/src/model/table.rs
@@ -539,9 +539,12 @@ pub struct TableHeader {
 
     /// The level of the header. Must not be zero.
     ///
-    /// This is used during repetition multiple headers at once. When a header
-    /// with a lower level starts repeating, all headers with a lower level stop
-    /// repeating.
+    /// This allows repeating multiple headers at once. Headers with different
+    /// levels can repeat together, as long as they have ascending levels.
+    ///
+    /// Notably, when a level with a lower level starts repeating, all higher
+    /// or equal level headers stop repeating (they are "replaced" by the new
+    /// header).
     #[default(NonZeroU32::ONE)]
     pub level: NonZeroU32,