Document Utility funcs, some layout funcs

3 files changed, 115 insertions, 3 deletions

diff --git a/library/src/layout/align.rs b/library/src/layout/align.rs
index 9fcb216f..7e2693aa 100644
--- a/library/src/layout/align.rs
+++ b/library/src/layout/align.rs
@@ -3,6 +3,16 @@ use crate::prelude::*;
 /// # Align
 /// Align content horizontally and vertically.
 ///
+/// ## Example
+/// ```
+/// #set align(center)
+///
+/// Centered text, a sight to see \
+/// In perfect balance, visually \
+/// Not left nor right, it stands alone \
+/// A work of art, a visual throne
+/// ```
+///
 /// ## Parameters
 /// - body: Content (positional, required)
 ///   The content to align.
@@ -10,6 +20,27 @@ use crate::prelude::*;
 /// - alignment: Axes<Option<GenAlign>> (positional, settable)
 ///   The alignment along both axes.
 ///
+///   Horizontal alignments can be `left`, `center`, `right`, `start`, or `end`.
+///   The `start` and `end` alignments are relative to the current
+///   [text direction](@text).
+///
+///   Vertical alignments can be `top`, `horizon`, or `bottom`.
+///
+///   To align along both axes at the same time, add the two alignments using
+///   the `+` operator to get a 2d alignment. For example, `top + right` aligns
+///   the content to the top right corner.
+///
+///   ### Example
+///   ```
+///   #set text(lang: "ar")
+///
+///   مثال
+///   #align(
+///     end + horizon,
+///     rect(inset: 12pt)[ركن]
+///   )
+///   ```
+///
 /// ## Category
 /// layout
 #[func]
diff --git a/library/src/layout/columns.rs b/library/src/layout/columns.rs
index e8ae5f35..0b1433e0 100644
--- a/library/src/layout/columns.rs
+++ b/library/src/layout/columns.rs
@@ -3,6 +3,34 @@ use crate::text::TextNode;
 
 /// # Columns
 /// Separate a region into multiple equally sized columns.
+/// 
+/// The column function allows to separate the interior of any container into
+/// multiple columns. It will not equalize the height of the columns, instead,
+/// the columns will take up the height of their container or the remaining
+/// height on the page. The columns function can break across pages if
+/// necessary.
+/// 
+/// ## Example
+/// ```
+/// = [An extraordinarily
+///   long heading]
+/// 
+/// #box(height: 68pt,
+///  columns(2, gutter: 11pt)[
+///    #set par(justify: true)
+///    This research was funded by the
+///    National Academy of Sciences.
+///    NAoS provided support for field 
+///    tests and interviews with a
+///    grant of up to USD 40.000 for a
+///    period of 6 months.
+///  ]
+/// )
+/// 
+/// In recent years, deep learning has
+/// increasingly been used to solve a
+/// variety of problems.
+/// ```
 ///
 /// ## Parameters
 /// - count: usize (positional, required)
@@ -114,7 +142,25 @@ impl Layout for ColumnsNode {
 }
 
 /// # Column Break
-/// A column break.
+/// A forced column break.
+/// 
+/// ## Example
+/// ```
+/// #set page(columns: 2)
+/// Preliminary findings from our
+/// ongoing research project have
+/// revealed a hitherto unknown
+/// phenomenon of extraordinary
+/// significance.
+/// 
+/// #colbreak()
+/// Through rigorous experimentation
+/// and analysis, we have discovered
+/// a hitherto uncharacterized process
+/// that defies our current
+/// understanding of the fundamental
+/// laws of nature.
+/// ```
 ///
 /// ## Parameters
 /// - weak: bool (named)
diff --git a/library/src/layout/container.rs b/library/src/layout/container.rs
index 933deeba..62e129b4 100644
--- a/library/src/layout/container.rs
+++ b/library/src/layout/container.rs
@@ -5,6 +5,21 @@ use crate::prelude::*;
 /// # Box
 /// An inline-level container that sizes content.
 ///
+/// Normally, all elements except inline math, text, and boxes are block-level
+/// and cannot occur inside of a paragraph. The box element allows you to create
+/// inline-level containers. Boxes take the size of their contents by default
+/// but can also be sized explicitly.
+///
+/// ## Example
+/// ```
+/// Refer to the docs
+/// #box(
+///   height: 9pt,
+///   image("docs.svg")
+/// )
+/// for more information.
+/// ```
+///
 /// ## Parameters
 /// - body: Content (positional)
 ///   The contents of the box.
@@ -79,6 +94,24 @@ impl Inline for BoxNode {}
 /// # Block
 /// A block-level container that places content into a separate flow.
 ///
+/// This can be used to force elements that would otherwise be inline to become
+/// block-level. This is especially useful when writing `{show}` rules.
+///
+/// ## Example
+/// ```
+/// [
+///   #show heading: it => it.title
+///   = No block
+///   Some text
+/// ]
+///
+/// [
+///   #show heading: it => block(it.title)
+///   = Block
+///   Some more text
+/// ]
+/// ```
+///
 /// ## Parameters
 /// - body: Content (positional)
 ///   The contents of the block.
@@ -87,11 +120,11 @@ impl Inline for BoxNode {}
 ///   The spacing around this block.
 ///
 /// - above: Spacing (named, settable)
-///   The spacing between the previous and this block. Takes precedence over
+///   The spacing between this block and its predecessor. Takes precedence over
 ///   `spacing`.
 ///
 /// - below: Spacing (named, settable)
-///   The spacing between this block and the following one. Takes precedence
+///   The spacing between this block and its successor. Takes precedence
 ///   over `spacing`.
 ///
 /// ## Category
@@ -110,6 +143,8 @@ impl BlockNode {
     #[property(skip)]
     pub const BELOW: VNode = VNode::block_spacing(Em::new(1.2).into());
     /// Whether this block must stick to the following one.
+    ///
+    /// Use this to prevent page breaks between e.g. a heading and its body.
     #[property(skip)]
     pub const STICKY: bool = false;