Document Utility funcs, some layout funcs

2 files changed, 57 insertions, 7 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;
         }