Finish the layout docs

3 files changed, 125 insertions, 1 deletions

diff --git a/library/src/layout/par.rs b/library/src/layout/par.rs
index c05ed2e8..25372bb6 100644
--- a/library/src/layout/par.rs
+++ b/library/src/layout/par.rs
@@ -14,6 +14,27 @@ use crate::text::{
 /// # Paragraph
 /// Arrange text, spacing and inline-level nodes into a paragraph.
 ///
+/// Although this function is primarily used in set rules to affect paragraph
+/// properties, it can also be used to explicitly render its argument onto a
+/// paragraph of its own.
+///
+/// ## Example
+/// ```
+/// #set par(indent: 1em, justify: true)
+/// #show par: set block(spacing: 0.65em)
+///
+/// We proceed by contradiction.
+/// Suppose that there exists a set
+/// of positive integers $a$, $b$, and
+/// $c$ that satisfies the equation
+/// $a^n + b^n = c^n$ for some
+/// integer value of $n > 2$.
+///
+/// Without loss of generality,
+/// let a be the smallest of the
+/// three integers. Then, we ...
+/// ```
+///
 /// ## Parameters
 /// - body: Content (positional, required)
 ///   The contents of the paragraph.
@@ -28,14 +49,57 @@ pub struct ParNode(pub StyleVec<Content>);
 #[node]
 impl ParNode {
     /// The indent the first line of a consecutive paragraph should have.
+    ///
+    /// The first paragraph on a page will never be indented.
+    ///
+    /// By typographic convention, paragraph breaks are indicated by either some
+    /// space between paragraphs or indented first lines. Consider turning the
+    /// [paragraph spacing](@block/spacing) off when using this property (e.g.
+    /// using `[#show par: set block(spacing: 0pt)]`).
     #[property(resolve)]
     pub const INDENT: Length = Length::zero();
+
     /// The spacing between lines.
+    ///
+    /// The default value is `{0.65em}`.
     #[property(resolve)]
     pub const LEADING: Length = Em::new(0.65).into();
+
     /// Whether to justify text in its line.
+    ///
+    /// Hyphenation will be enabled for justified paragraphs if the [text
+    /// property hyphenate](@text/hyphenate) is set to `{auto}` and the current
+    /// language is known.
+    ///
+    /// Note that the current [alignment](@align) still has an effect on the
+    /// placement of the last line except if it ends with a [justified line
+    /// break](@linebreak/justify).
     pub const JUSTIFY: bool = false;
+
     /// How to determine line breaks.
+    ///
+    /// When this property is set to `{auto}`, its default value, optimized line
+    /// breaks will be used for justified paragraphs. Enabling optimized line
+    /// breaks for ragged paragraphs may also be worthwhile to improve the
+    /// appearance of the text.
+    ///
+    /// # Example
+    /// ```
+    /// #set page(width: 190pt)
+    /// #set par(linebreaks: "simple")
+    /// Some texts are frustratingly
+    /// challenging to break in a
+    /// visually pleasing way. This
+    /// very aesthetic example is one
+    /// of them.
+    ///
+    /// #set par(linebreaks: "optimized")
+    /// Some texts are frustratingly
+    /// challenging to break in a
+    /// visually pleasing way. This
+    /// very aesthetic example is one
+    /// of them.
+    /// ```
     pub const LINEBREAKS: Smart<Linebreaks> = Smart::Auto;
 
     fn construct(_: &Vm, args: &mut Args) -> SourceResult<Content> {
@@ -145,6 +209,9 @@ castable! {
     /// Determine the linebreaks in a simple first-fit style.
     "simple" => Self::Simple,
     /// Optimize the linebreaks for the whole paragraph.
+    ///
+    /// Typst will try to produce more evenly filled lines of text by
+    /// considering the whole paragraph when calculating line breaks.
     "optimized" => Self::Optimized,
 }
 
@@ -155,6 +222,10 @@ castable! {
 /// [for loops](/docs/reference/concepts#for-loop). Multiple consecutive
 /// paragraph breaks collapse into a single one.
 ///
+/// ## Syntax
+/// Instead of calling this function, you can insert two empty lines in your
+/// markup to create a paragraph break.
+///
 /// ## Example
 /// ```
 /// #for i in range(3) {
diff --git a/library/src/layout/place.rs b/library/src/layout/place.rs
index 406aa862..26ab7b18 100644
--- a/library/src/layout/place.rs
+++ b/library/src/layout/place.rs
@@ -3,16 +3,55 @@ use crate::prelude::*;
 /// # Place
 /// Place content at an absolute position.
 ///
+/// Placed content will not affect the position of other content. Place is
+/// always relative to its parent container and will be in the foreground of all
+/// other content in the container. Page margins will be respected.
+///
+///
+/// ## Example
+/// ```
+/// #set page(height: 60pt)
+/// Hello, world!
+///
+/// #place(
+///   top + right,
+///   square(
+///     width: 10pt,
+///     stroke: 1pt + blue
+///   ),
+/// )
+/// ```
+///
 /// ## Parameters
 /// - alignment: Axes<Option<GenAlign>> (positional)
 ///   Relative to which position in the parent container to place the content.
 ///
+///   When an axis of the page is `{auto}` sized, all alignments relative to that
+///   axis will be ignored, instead, the item will be placed in the origin of the
+///   axis.
+///
 /// - body: Content (positional, required)
 ///   The content to place.
 ///
 /// - dx: Rel<Length> (named)
 ///   The horizontal displacement of the placed content.
 ///
+///   ### Example
+///   ```
+///   #set align(center)
+///   
+///   #box(
+///     width: 80pt,
+///     height: 80pt,
+///     {
+///       for i in range(18) {
+///         let amount = i * 4pt
+///         place(dx: amount, dy: amount)[A]
+///       }
+///     }
+///   )
+///   ```
+///
 /// - dy: Rel<Length> (named)
 ///   The vertical displacement of the placed content.
 ///
diff --git a/library/src/layout/stack.rs b/library/src/layout/stack.rs
index c423b1a3..39e040b3 100644
--- a/library/src/layout/stack.rs
+++ b/library/src/layout/stack.rs
@@ -4,7 +4,21 @@ use super::{AlignNode, Spacing};
 use crate::prelude::*;
 
 /// # Stack
-/// Arrange content and spacing along an axis.
+/// Arrange content and spacing horizontally or vertically.
+///
+/// The stack places a list of items along an axis, with optional spacing
+/// between each item.
+///
+/// ## Example
+/// ```
+/// #stack(
+///   dir: ttb,
+///
+///   rect(width: 40pt),
+///   rect(width: 120pt),
+///   rect(width: 90pt),
+/// )
+/// ```
 ///
 /// ## Parameters
 /// - items: StackChild (positional, variadic)