Document Utility funcs, some layout funcs

6 files changed, 177 insertions, 12 deletions

diff --git a/library/src/compute/data.rs b/library/src/compute/data.rs
index e947d617..3751292c 100644
--- a/library/src/compute/data.rs
+++ b/library/src/compute/data.rs
@@ -14,7 +14,7 @@ use crate::prelude::*;
 ///
 /// ## Example
 /// ```
-/// #let results = csv("/data.csv")
+/// #let results = csv("data.csv")
 ///
 /// #table(
 ///   columns: 2,
@@ -133,8 +133,8 @@ fn format_csv_error(error: csv::Error) -> String {
 ///   °{day.unit}
 /// ]
 ///
-/// #forecast(json("/monday.json"))
-/// #forecast(json("/tuesday.json"))
+/// #forecast(json("monday.json"))
+/// #forecast(json("tuesday.json"))
 /// ```
 ///
 /// ## Parameters
@@ -180,7 +180,10 @@ fn convert_json(value: serde_json::Value) -> Value {
 /// Format the user-facing JSON error message.
 fn format_json_error(error: serde_json::Error) -> String {
     assert!(error.is_syntax() || error.is_eof());
-    format!("failed to parse json file: syntax error in line {}", error.line())
+    format!(
+        "failed to parse json file: syntax error in line {}",
+        error.line()
+    )
 }
 
 /// # XML
@@ -225,7 +228,7 @@ fn format_json_error(error: serde_json::Error) -> String {
 ///   }
 /// }
 ///
-/// #let file = xml("/example.xml")
+/// #let file = xml("example.xml")
 /// #for child in file(0).children {
 ///   if (type(child) == "dictionary") {
 ///     article(child)
diff --git a/library/src/compute/utility.rs b/library/src/compute/utility.rs
index 1a3511d0..f8a6d4dc 100644
--- a/library/src/compute/utility.rs
+++ b/library/src/compute/utility.rs
@@ -6,6 +6,20 @@ use crate::text::Case;
 /// # Blind Text
 /// Create blind text.
 ///
+/// This function yields a Latin-like _Lorem Ipsum_ blind text with the given
+/// number of words. The sequence of words generated by the function is always
+/// the same but randomly chosen. As usual for blind texts, it does not make any
+/// sense. Use it as a placeholder to try layouts.
+///
+/// ## Example
+/// ```
+/// = Blind Text
+/// #lorem(30)
+///
+/// = More Blind Text
+/// #lorem(15)
+/// ```
+///
 /// ## Parameters
 /// - words: usize (positional, required)
 ///   The length of the blind text in words.
@@ -21,12 +35,41 @@ pub fn lorem(args: &mut Args) -> SourceResult<Value> {
 /// # Numbering
 /// Apply a numbering pattern to a sequence of numbers.
 ///
+/// Numbering patterns are strings that define how a sequence of numbers should
+/// be rendered as text. The patterns consist of [counting
+/// symbols](#parameters--pattern) for which the actual number is substituted,
+/// their prefixes, and one suffix. The prefixes and the suffix are repeated as-is.
+///
+/// ## Example
+/// ```
+/// #numbering("1.1)", 1, 2, 3) \
+/// #numbering("1.b.i", 1, 2) \
+/// #numbering("I – 1", 12, 2)
+/// ```
+///
 /// ## Parameters
 /// - pattern: NumberingPattern (positional, required)
 ///   A string that defines how the numbering works.
 ///
+///   **Counting symbols** are `1`, `a`, `A`, `i`, `I` and `*`. They are replaced
+///   by the number in the sequence, in the given case.
+///
+///   The `*` character means that symbols should be used to count, in the order
+///   of `*`, `†`, `‡`, `§`, `¶`, and `‖`. If there are more than six items, the
+///   number is represented using multiple symbols.
+///
+///   **Suffixes** are all characters after the last counting symbol. They are
+///   repeated as-is at the end of any rendered number.
+///
+///   **Prefixes** are all characters that are neither counting symbols nor
+///   suffixes. They are repeated as-is at in front of their rendered equivalent
+///   of their counting symbol.
+///
 /// - numbers: NonZeroUsize (positional, variadic)
-///   The numbers to apply the pattern to.
+///   The numbers to apply the pattern to. Must be positive.
+///
+///   If more numbers than counting symbols are given, the last counting symbol
+///   with its prefix is repeated.
 ///
 /// ## Category
 /// utility
@@ -96,7 +139,11 @@ impl FromStr for NumberingPattern {
             };
 
             let prefix = pattern[handled..i].into();
-            let case = if c.is_uppercase() { Case::Upper } else { Case::Lower };
+            let case = if c.is_uppercase() {
+                Case::Upper
+            } else {
+                Case::Lower
+            };
             pieces.push((prefix, kind, case));
             handled = i + 1;
         }
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;
 
diff --git a/src/syntax/source.rs b/src/syntax/source.rs
index 6144d524..9b76af12 100644
--- a/src/syntax/source.rs
+++ b/src/syntax/source.rs
@@ -124,8 +124,11 @@ impl Source {
         }
 
         // Recalculate the line starts after the edit.
-        self.lines
-            .extend(lines_from(start_byte, start_utf16, &self.text[start_byte..]));
+        self.lines.extend(lines_from(
+            start_byte,
+            start_utf16,
+            &self.text[start_byte..],
+        ));
 
         // Incrementally reparse the replaced range.
         let mut root = std::mem::take(&mut self.root).into_inner();