Repository: typst/typst
File: crates/typst-library/src/layout/grid/mod.rs (Rust)

Code before:
/// #grid(
///   columns: 5,
///
///   // By a single value
///   align: center,
///   // By a single but more complicated value
///   inset: (x: 2pt, y: 3pt),
///   // By an array of values (cycling)
///   fill: (rgb("#239dad50"), none),
///   // By a function that returns a value
///   stroke: (x, y) => if calc.rem(x + y, 3) == 0 { 0.5pt },
///
///   ..range(5 * 3).map(n => numbering("A", n + 1))
/// )
/// ```
///
/// On top of that, you may [apply styling rules]($styling) to [`grid`] and
/// [`grid.cell`]. Especially, the [`x`]($grid.cell.x) and [`y`]($grid.cell.y)
/// fields of `grid.cell` can be used in a [`where`]($function.where) selector,
/// making it possible to style cells at specific columns or rows, or individual
/// positions.
///
/// Locating most of your styling in set and show rules is
/// recommended, as it keeps the grid's or table's actual usages clean and easy
/// to read. It also allows you to easily change the grid's appearance in one
/// place.
///
/// ## Stroke styling precedence
/// As explained above, there are three ways to set the stroke of a grid cell:
/// through [`{grid.cell}`'s `stroke` field]($grid.cell.stroke), by using
/// [`{grid.hline}`]($grid.hline) and [`{grid.vline}`]($grid.vline), or by
/// setting the [`{grid}`'s `stroke` field]($grid.stroke). When multiple of
/// these settings are present and conflict, the `hline` and `vline` settings
/// take the highest precedence, followed by the `cell` settings, and finally
/// the `grid` settings.
///
/// Furthermore, strokes of a repeated grid header or footer will take
/// precedence over regular cell strokes.
#[elem(scope)]
pub struct GridElem {
    /// The column sizes.
    ///
    /// Either specify a track size array or provide an integer to create a grid
    /// with that many `{auto}`-sized columns. Note that opposed to rows and
    /// gutters, providing a single track size will only ever create a single
    /// column.
    ///
    /// See the [track size section](#track-size) above for more details.
    pub columns: TrackSizings,

    /// The row sizes.

Review comment (refactor):
For tables, 100%. For grids, a bit less so because they are not semantic so a set rule could potentially affect implementation details with other grids within your grid. Maybe, we should move this to the table docs?

Code after:
/// #grid(
///   columns: 5,
///
///   // By a single value
///   align: center,
///   // By a single but more complicated value
///   inset: (x: 2pt, y: 3pt),
///   // By an array of values (cycling)
///   fill: (rgb("#239dad50"), none),
///   // By a function that returns a value
///   stroke: (x, y) => if calc.rem(x + y, 3) == 0 { 0.5pt },
///
///   ..range(5 * 3).map(n => numbering("A", n + 1))
/// )
/// ```
///
/// On top of that, you may [apply styling rules]($styling) to [`grid`] and
/// [`grid.cell`]. Especially, the [`x`]($grid.cell.x) and [`y`]($grid.cell.y)
/// fields of `grid.cell` can be used in a [`where`]($function.where) selector,
/// making it possible to style cells at specific columns or rows, or individual
/// positions.
///
/// ## Stroke styling precedence
/// As explained above, there are three ways to set the stroke of a grid cell:
/// through [`{grid.cell}`'s `stroke` field]($grid.cell.stroke), by using
/// [`{grid.hline}`]($grid.hline) and [`{grid.vline}`]($grid.vline), or by
/// setting the [`{grid}`'s `stroke` field]($grid.stroke). When multiple of
/// these settings are present and conflict, the `hline` and `vline` settings
/// take the highest precedence, followed by the `cell` settings, and finally
/// the `grid` settings.
///
/// Furthermore, strokes of a repeated grid header or footer will take
/// precedence over regular cell strokes.
#[elem(scope)]
pub struct GridElem {
    /// The column sizes.
    ///
    /// Either specify a track size array or provide an integer to create a grid
    /// with that many `{auto}`-sized columns. Note that opposed to rows and
    /// gutters, providing a single track size will only ever create a single
    /// column.
    ///
    /// See the [track size section](#track-size) above for more details.
    pub columns: TrackSizings,

    /// The row sizes.
    ///
    /// If there are more cells than fit the defined rows, the last row is
    /// repeated until there are no more cells.
    ///
    /// See the [track size section](#track-size) above for more details.