From 5289bdae504852ac9a721ddf413b669e2c6852af Mon Sep 17 00:00:00 2001 From: PgBiel <9021226+PgBiel@users.noreply.github.com> Date: Thu, 1 May 2025 00:04:19 -0300 Subject: [PATCH] update some field docs --- crates/typst-layout/src/grid/layouter.rs | 72 ++++++++++++++---------- 1 file changed, 41 insertions(+), 31 deletions(-) diff --git a/crates/typst-layout/src/grid/layouter.rs b/crates/typst-layout/src/grid/layouter.rs index 410e3c66c..0b35278c3 100644 --- a/crates/typst-layout/src/grid/layouter.rs +++ b/crates/typst-layout/src/grid/layouter.rs @@ -32,7 +32,7 @@ pub struct GridLayouter<'a> { pub(super) rcols: Vec, /// The sum of `rcols`. pub(super) width: Abs, - /// Resolve row sizes, by region. + /// Resolved row sizes, by region. pub(super) rrows: Vec>, /// Rows in the current region. pub(super) lrows: Vec, @@ -51,15 +51,16 @@ pub struct GridLayouter<'a> { pub(super) finished_header_rows: Vec, /// Whether this is an RTL grid. pub(super) is_rtl: bool, - /// Currently repeating headers, one per level. - /// Sorted by increasing levels. + /// Currently repeating headers, one per level. Sorted by increasing + /// levels. /// /// Note that some levels may be absent, in particular level 0, which does - /// not exist (so the first level is >= 1). + /// not exist (so all levels are >= 1). pub(super) repeating_headers: Vec<&'a Header>, /// Headers, repeating or not, awaiting their first successful layout. /// Sorted by increasing levels. pub(super) pending_headers: &'a [Repeatable
], + /// Next headers to be processed. pub(super) upcoming_headers: &'a [Repeatable
], /// State of the row being currently laid out. /// @@ -84,28 +85,27 @@ pub(super) struct Current { /// find a new header inside the region (not at the top), so this field /// is required to access information from the top of the region. /// - /// This is used for orphan prevention checks (if there are no rows other - /// than repeated header rows upon finishing a region, we'd have orphans). - /// Note that non-repeated and pending repeated header rows are not included - /// in this number as they use a separate mechanism for orphan prevention - /// (`lrows_orphan_shapshot` field). - /// - /// In addition, this information is used on finish region to calculate the - /// total height of resolved header rows at the top of the region, which is - /// used by multi-page rowspans so they can properly skip the header rows - /// at the top of the region during layout. + /// This information is used on finish region to calculate the total height + /// of resolved header rows at the top of the region, which is used by + /// multi-page rowspans so they can properly skip the header rows at the + /// top of each region during layout. pub(super) repeated_header_rows: usize, - /// The end bound of the last repeating header at the start of the region. - /// The last row might have disappeared due to being empty, so this is how - /// we can become aware of that. Line layout uses this to determine when to - /// prioritize the last lines under a header. + /// The end bound of the row range of the last repeating header at the + /// start of the region. /// - /// A value of zero indicates no headers were placed. + /// The last row might have disappeared from layout due to being empty, so + /// this is how we can become aware of where the last header ends without + /// having to check the vector of rows. Line layout uses this to determine + /// when to prioritize the last lines under a header. + /// + /// A value of zero indicates no repeated headers were placed. pub(super) last_repeated_header_end: usize, - /// Stores the length of `lrows` before a sequence of trailing rows - /// equipped with orphan prevention were laid out. In this case, if no more - /// rows without orphan prevention are laid out after those rows before the - /// region ends, the rows will be removed. + /// Stores the length of `lrows` before a sequence of rows equipped with + /// orphan prevention was laid out. In this case, if no more rows without + /// orphan prevention are laid out after those rows before the region ends, + /// the rows will be removed, and there may be an attempt to place them + /// again in the new region. Effectively, this is the mechanism used for + /// orphan prevention of rows. /// /// At the moment, this is only used by repeated headers (they aren't laid /// out if alone in the region) and by new headers, which are moved to the @@ -116,14 +116,16 @@ pub(super) struct Current { /// The total simulated height for all headers currently in /// `repeating_headers` and `pending_headers`. /// - /// This field is reset in `layout_header` and properly updated by + /// This field is reset on each new region and properly updated by /// `layout_auto_row` and `layout_relative_row`, and should not be read /// before all header rows are fully laid out. It is usually fine because /// header rows themselves are unbreakable, and unbreakable rows do not /// need to read this field at all. /// /// This height is not only computed at the beginning of the region. It is - /// updated whenever a new header is found. + /// updated whenever a new header is found, subtracting the height of + /// headers which stopped repeating and adding the height of all new + /// headers. pub(super) header_height: Abs, /// The height of effectively repeating headers, that is, ignoring /// non-repeating pending headers. @@ -134,9 +136,14 @@ pub(super) struct Current { /// but disappear on new regions, so they can be ignored. pub(super) repeating_header_height: Abs, /// The height for each repeating header that was placed in this region. - /// Note that this includes headers not at the top of the region (pending - /// headers), and excludes headers removed by virtue of a new, conflicting - /// header being found. + /// Note that this includes headers not at the top of the region, before + /// their first repetition (pending headers), and excludes headers removed + /// by virtue of a new, conflicting header being found (short-lived + /// headers). + /// + /// This is used to know how much to update `repeating_header_height` by + /// when finding a new header and causing existing repeating headers to + /// stop. pub(super) repeating_header_heights: Vec, /// The simulated footer height for this region. /// @@ -147,7 +154,7 @@ pub(super) struct Current { /// Data about the row being laid out right now. #[derive(Debug, Default)] pub(super) struct RowState { - /// If this is `Some`, this will receive the currently laid out row's + /// If this is `Some`, this will be updated by the currently laid out row's /// height if it is auto or relative. This is used for header height /// calculation. pub(super) current_row_height: Option, @@ -155,7 +162,7 @@ pub(super) struct RowState { /// That is, headers and footers which are not immediately followed or /// preceded (respectively) by conflicting headers and footers of same or /// lower level, or the end or start of the table (respectively), which - /// would cause them to stop repeating. + /// would cause them to never repeat, even once. /// /// If this is `false`, the next row to be laid out will remove an active /// orphan snapshot and will flush pending headers, as there is no risk @@ -163,12 +170,15 @@ pub(super) struct RowState { pub(super) in_active_repeatable: bool, } +/// Data about laid out repeated header rows for a specific finished region. #[derive(Debug, Default)] pub(super) struct FinishedHeaderRowInfo { /// The amount of repeated headers at the top of the region. pub(super) repeated: usize, - /// The end bound of the last repeated header at the top of the region. + /// The end bound of the row range of the last repeated header at the top + /// of the region. pub(super) last_repeated_header_end: usize, + /// The total height of repeated headers at the top of the region. pub(super) height: Abs, }