Some layout documentation

4 files changed, 139 insertions, 1 deletions

diff --git a/library/src/layout/grid.rs b/library/src/layout/grid.rs
index eb45cfbe..85d464b1 100644
--- a/library/src/layout/grid.rs
+++ b/library/src/layout/grid.rs
@@ -5,19 +5,83 @@ use super::Spacing;
 /// # Grid
 /// Arrange content in a grid.
 ///
+/// The grid element allows you to arrange content in a grid. You can define the
+/// number of rows and columns, as well as the size of the gutters between them.
+/// There are multiple sizing modes for columns and rows, including fixed sizes,
+/// that can be used to create complex layouts.
+///
+/// The sizing of the grid is determined by the track sizes specified in the
+/// arguments. Because each of the sizing parameters accepts the same values, we
+/// will explain them here:
+///
+/// Each sizing argument accepts an array of track sizes. A track size is either
+/// - a fixed length (e.g. `10pt`). The track will be exactly this size.
+/// - `{auto}`. The track will be sized to fit its contents. It will be at most
+///   as large as the remaining space. If there is more than one `auto` track
+///   that, together, claim more than the available space, they will be resized
+///   to fit the available space.
+/// - a `fractional` length (e.g. `{1fr}`). Once all other tracks have been
+///   sized, the remaining space will be divided among the fractional tracks
+///   according to their fraction. For example, if there are two fractional
+///   tracks, each with a fraction of `1`, they will each take up half of the
+///   remaining space.
+///
+/// To specify a single track, the array can be omitted in favor of a single
+/// value. To specify multiple `{auto}` tracks, enter the number of tracks
+/// instead of a value. For example, `columns: {3}` is equivalent to
+/// `columns: {(auto, auto, auto)}`.
+///
+/// ## Example
+/// ```
+/// #set text(hyphenate: true)
+/// #let cell = rect.with(
+///     inset: 6pt,
+///     fill: rgb("e4e5ea"),
+///     width: 100%,
+///     radius: 6pt
+///   )
+///   
+///   #grid(
+///     columns: (60pt, 1fr, 60pt),
+///     rows: (60pt, auto),
+///     gutter: 3pt,
+///     cell(height: 100%)[*Easy to learn*],
+///     cell(height: 100%)[Great output],
+///     cell(height: 100%)[*Intuitive*],
+///     cell[*Our best Typst yet*],
+///     cell[
+///       Responsive design in print
+///       for everyone
+///     ],
+///     cell[*One more thing...*],
+///   )
+/// ```
+///
 /// ## Parameters
 /// - cells: Content (positional, variadic)
 ///   The contents of the table cells.
 ///
+///   The cells are populated in row-major order.
+///
 /// - rows: TrackSizings (named)
 ///   Defines the row sizes.
 ///
+///   If there are more cells than fit the defined rows, the last row is
+///   repeated until there are no more cells.
+///
 /// - columns: TrackSizings (named)
 ///   Defines 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.
+///
 /// - gutter: TrackSizings (named)
 ///   Defines the gaps between rows & columns.
 ///
+///   If there are more gutters than defined sizes, the last gutter is repeated.
+///
 /// - column-gutter: TrackSizings (named)
 ///   Defines the gaps between columns. Takes precedence over `gutter`.
 ///
diff --git a/library/src/layout/hide.rs b/library/src/layout/hide.rs
index f7f19549..dec6dd1c 100644
--- a/library/src/layout/hide.rs
+++ b/library/src/layout/hide.rs
@@ -3,6 +3,17 @@ use crate::prelude::*;
 /// # Hide
 /// Hide content without affecting layout.
 ///
+/// The `hide` function allows you to hide content while the layout still 'sees'
+/// it. This is useful to create layout items that are exactly as large as some
+/// content. It may also be useful to redact content because its arguments are
+/// not included in the output.
+///
+/// ## Example
+/// ```
+/// Hello Jane \
+/// #hide[Hello] Joe
+/// ```
+///
 /// ## Parameters
 /// - body: Content (positional, required)
 ///   The content to hide.
diff --git a/library/src/layout/pad.rs b/library/src/layout/pad.rs
index 7825d133..13b573bf 100644
--- a/library/src/layout/pad.rs
+++ b/library/src/layout/pad.rs
@@ -1,7 +1,20 @@
 use crate::prelude::*;
 
 /// # Padding
-/// Pad content at the sides.
+/// Add spacing around content.
+///
+/// The `pad` function adds spacing around content. The spacing can be specified
+/// for each side individually, or for all sides at once by specifying a
+/// positional argument.
+///
+/// ## Example
+/// ```
+/// #set align(center)
+///
+/// #pad(16pt, image("typing.jpg"))
+/// _Typing speeds can be
+/// measured in words per minute._
+/// ```
 ///
 /// ## Parameters
 /// - body: Content (positional, required)
diff --git a/library/src/layout/transform.rs b/library/src/layout/transform.rs
index 6d2caf1d..92a31780 100644
--- a/library/src/layout/transform.rs
+++ b/library/src/layout/transform.rs
@@ -5,10 +5,33 @@ use crate::prelude::*;
 /// # Move
 /// Move content without affecting layout.
 ///
+/// The `move` function allows you to hide content while the layout still 'sees'
+/// it at the original positions. Containers will still be sized as if the content
+/// was not moved.
+///
+/// ## Example
+/// ```
+/// #rect(
+///   move(
+///     dx: 6pt, dy: 6pt,
+///     rect(
+///       inset: 8pt,
+///       fill: white,
+///       stroke: black,
+///       [Abra cadabra]
+///     )
+///   )
+/// )
+/// ```
+///
 /// ## Parameters
 /// - body: Content (positional, required)
 ///   The content to move.
 ///
+///   ### Example
+///   ```
+///   Hello, world!#move(dy: -2pt)[!]#move(dy: 2pt)[!]
+///
 /// - dx: Rel<Length> (named)
 ///   The horizontal displacement of the content.
 ///
@@ -62,6 +85,19 @@ impl Inline for MoveNode {}
 /// # Rotate
 /// Rotate content with affecting layout.
 ///
+/// Rotate an element by a given angle. The layout will act as if the element
+/// was not rotated.
+///
+/// ## Example
+/// ```
+/// {
+///   range(16)
+///     .map(i =>
+///       rotate(360deg / 15 * i)[X]
+///     ).join(h(1fr))
+/// }
+/// ```
+///
 /// ## Parameters
 /// - body: Content (positional, required)
 ///   The content to rotate.
@@ -121,6 +157,16 @@ impl Inline for RotateNode {}
 /// # Scale
 /// Scale content without affecting layout.
 ///
+/// The `scale` function allows you to scale and mirror content without
+/// affecting the layout.
+///
+///
+/// ## Example
+/// ```
+/// #set align(center)
+/// #scale(x: -100%)[👍]👩‍🦱👍
+/// ```
+///
 /// ## Parameters
 /// - body: Content (positional, required)
 ///   The content to scale.
@@ -128,9 +174,13 @@ impl Inline for RotateNode {}
 /// - x: Ratio (named)
 ///   The horizontal scaling factor.
 ///
+///   The body will be mirrored horizontally if the parameter is negative.
+///
 /// - y: Ratio (named)
 ///   The vertical scaling factor.
 ///
+///   The body will be mirrored vertically if the parameter is negative.
+///
 /// ## Category
 /// layout
 #[func]