Make Rust happier about the inline documentation

11 files changed, 97 insertions, 92 deletions

diff --git a/library/src/math/accent.rs b/library/src/math/accent.rs
index 223ada4f..aa6d0523 100644
--- a/library/src/math/accent.rs
+++ b/library/src/math/accent.rs
@@ -9,23 +9,22 @@ const ACCENT_SHORT_FALL: Em = Em::new(0.5);
 /// Attach an accent to a base.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// $grave(a) = accent(a, `)$ \
 /// $arrow(a) = accent(a, arrow)$ \
 /// $tilde(a) = accent(a, \u{0303})$
 /// ```
 ///
 /// ## Parameters
-/// - base: Content (positional, required)
+/// - base: `Content` (positional, required)
 ///   The base to which the accent is applied.
 ///   May consist of multiple letters.
 ///
-///   ### Example
-///   ```
+///   ```example
 ///   $arrow(A B C)$
 ///   ```
 ///
-/// - accent: char (positional, required)
+/// - accent: `char` (positional, required)
 ///   The accent to apply to the base.
 ///
 ///   Supported accents include:
diff --git a/library/src/math/align.rs b/library/src/math/align.rs
index e8a9c14a..a9005dfd 100644
--- a/library/src/math/align.rs
+++ b/library/src/math/align.rs
@@ -4,7 +4,7 @@ use super::*;
 /// A math alignment point: `&`, `&&`.
 ///
 /// ## Parameters
-/// - index: usize (positional, required)
+/// - index: `usize` (positional, required)
 ///   The alignment point's index.
 ///
 /// ## Category
diff --git a/library/src/math/attach.rs b/library/src/math/attach.rs
index 7e6ac388..31dc75ab 100644
--- a/library/src/math/attach.rs
+++ b/library/src/math/attach.rs
@@ -8,18 +8,18 @@ use super::*;
 /// indicate a bottom attachment and the hat (`^`) to indicate a top attachment.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// $ sum_(i=0)^n a_i = 2^(1+i) $
 /// ```
 ///
 /// ## Parameters
-/// - base: Content (positional, required)
+/// - base: `Content` (positional, required)
 ///   The base to which things are attached.
 ///
-/// - top: Content (named)
+/// - top: `Content` (named)
 ///   The top attachment.
 ///
-/// - bottom: Content (named)
+/// - bottom: `Content` (named)
 ///   The bottom attachment.
 ///
 /// ## Category
@@ -84,12 +84,12 @@ impl LayoutMath for AttachNode {
 /// Force a base to display attachments as scripts.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// $ scripts(sum)_1^2 != sum_1^2 $
 /// ```
 ///
 /// ## Parameters
-/// - base: Content (positional, required)
+/// - base: `Content` (positional, required)
 ///   The base to attach the scripts to.
 ///
 /// ## Category
@@ -116,12 +116,12 @@ impl LayoutMath for ScriptsNode {
 /// Force a base to display attachments as limits.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// $ limits(A)_1^2 != A_1^2 $
 /// ```
 ///
 /// ## Parameters
-/// - base: Content (positional, required)
+/// - base: `Content` (positional, required)
 ///   The base to attach the limits to.
 ///
 /// ## Category
diff --git a/library/src/math/delimited.rs b/library/src/math/delimited.rs
index 5b9decb6..511f1a7b 100644
--- a/library/src/math/delimited.rs
+++ b/library/src/math/delimited.rs
@@ -10,16 +10,16 @@ pub(super) const DELIM_SHORT_FALL: Em = Em::new(0.1);
 /// unmatched delimiters and to control the delimiter scaling more precisely.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// $ lr(]a, b/2]) $
 /// $ lr(]sum_(x=1)^n] x, size: #50%) $
 /// ```
 ///
 /// ## Parameters
-/// - body: Content (positional, variadic)
+/// - body: `Content` (positional, variadic)
 ///   The delimited content, including the delimiters.
 ///
-/// - size: Rel<Length> (named)
+/// - size: `Rel<Length>` (named)
 ///   The size of the brackets, relative to the height of the wrapped content.
 ///
 ///   Defaults to `{100%}`.
@@ -120,12 +120,12 @@ fn scale(
 /// Floor an expression.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// $ floor(x/2) $
 /// ```
 ///
 /// ## Parameters
-/// - body: Content (positional, required)
+/// - body: `Content` (positional, required)
 ///   The expression to floor.
 ///
 /// ## Category
@@ -139,12 +139,12 @@ pub fn floor(args: &mut Args) -> SourceResult<Value> {
 /// Ceil an expression.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// $ ceil(x/2) $
 /// ```
 ///
 /// ## Parameters
-/// - body: Content (positional, required)
+/// - body: `Content` (positional, required)
 ///   The expression to ceil.
 ///
 /// ## Category
@@ -158,12 +158,12 @@ pub fn ceil(args: &mut Args) -> SourceResult<Value> {
 /// Take the absolute value of an expression.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// $ abs(x/2) $
 /// ```
 ///
 /// ## Parameters
-/// - body: Content (positional, required)
+/// - body: `Content` (positional, required)
 ///   The expression to take the absolute value of.
 ///
 /// ## Category
@@ -177,12 +177,12 @@ pub fn abs(args: &mut Args) -> SourceResult<Value> {
 /// Take the norm of an expression.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// $ norm(x/2) $
 /// ```
 ///
 /// ## Parameters
-/// - body: Content (positional, required)
+/// - body: `Content` (positional, required)
 ///   The expression to take the norm of.
 ///
 /// ## Category
diff --git a/library/src/math/frac.rs b/library/src/math/frac.rs
index 283686c8..cdf533da 100644
--- a/library/src/math/frac.rs
+++ b/library/src/math/frac.rs
@@ -5,23 +5,23 @@ const FRAC_AROUND: Em = Em::new(0.1);
 /// # Fraction
 /// A mathematical fraction.
 ///
+/// ## Example
+/// ```example
+/// $ 1/2 < (x+1)/2 $
+/// $ ((x+1)) / 2 = frac(a, b) $
+/// ```
+///
 /// ## Syntax
 /// This function also has dedicated syntax: Use a slash to turn neighbouring
 /// expressions into a fraction. Multiple atoms can be grouped into a single
 /// expression using round grouping parenthesis. Such parentheses are removed
 /// from the output, but you can nest multiple to force them.
 ///
-/// ## Example
-/// ```
-/// $ 1/2 < (x+1)/2 $
-/// $ ((x+1)) / 2 = frac(a, b) $
-/// ```
-///
 /// ## Parameters
-/// - num: Content (positional, required)
+/// - num: `Content` (positional, required)
 ///   The fraction's numerator.
 ///
-/// - denom: Content (positional, required)
+/// - denom: `Content` (positional, required)
 ///   The fraction's denominator.
 ///
 /// ## Category
@@ -55,15 +55,15 @@ impl LayoutMath for FracNode {
 /// A binomial expression.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// $ binom(n, k) $
 /// ```
 ///
 /// ## Parameters
-/// - upper: Content (positional, required)
+/// - upper: `Content` (positional, required)
 ///   The binomial's upper index.
 ///
-/// - lower: Content (positional, required)
+/// - lower: `Content` (positional, required)
 ///   The binomial's lower index.
 ///
 /// ## Category
diff --git a/library/src/math/matrix.rs b/library/src/math/matrix.rs
index c47f2d5e..c7b94417 100644
--- a/library/src/math/matrix.rs
+++ b/library/src/math/matrix.rs
@@ -10,13 +10,13 @@ const VERTICAL_PADDING: Ratio = Ratio::new(0.1);
 /// Content in the vector's elements can be aligned with the `&` symbol.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// $ vec(a, b, c) dot vec(1, 2, 3)
 ///     = a + 2b + 3c $
 /// ```
 ///
 /// ## Parameters
-/// - elements: Content (positional, variadic)
+/// - elements: `Content` (positional, variadic)
 ///   The elements of the vector.
 ///
 /// ## Category
@@ -30,8 +30,7 @@ pub struct VecNode(Vec<Content>);
 impl VecNode {
     /// The delimiter to use.
     ///
-    /// # Example
-    /// ```
+    /// ```example
     /// #set math.vec(delim: "[")
     /// $ vec(1, 2) $
     /// ```
@@ -62,7 +61,7 @@ impl LayoutMath for VecNode {
 /// Content in cells that are in the same row can be aligned with the `&` symbol.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// $ mat(
 ///   1, 2, ..., 10;
 ///   2, 2, ..., 10;
@@ -72,11 +71,10 @@ impl LayoutMath for VecNode {
 /// ```
 ///
 /// ## Parameters
-/// - rows: Array (positional, variadic)
+/// - rows: `Array` (positional, variadic)
 ///   An array of arrays with the rows of the matrix.
 ///
-///   ### Example
-///   ```
+///   ```example
 ///   #let data = ((1, 2, 3), (4, 5, 6))
 ///   #let matrix = math.mat(..data)
 ///   $ v := matrix $
@@ -93,8 +91,7 @@ pub struct MatNode(Vec<Vec<Content>>);
 impl MatNode {
     /// The delimiter to use.
     ///
-    /// # Example
-    /// ```
+    /// ```example
     /// #set math.mat(delim: "[")
     /// $ mat(1, 2; 3, 4) $
     /// ```
@@ -140,7 +137,7 @@ impl LayoutMath for MatNode {
 /// Content across different branches can be aligned with the `&` symbol.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// $ f(x, y) := cases(
 ///   1 "if" (x dot y)/2 <= 0,
 ///   2 "if" x "is even",
@@ -150,7 +147,7 @@ impl LayoutMath for MatNode {
 /// ```
 ///
 /// ## Parameters
-/// - branches: Content (positional, variadic)
+/// - branches: `Content` (positional, variadic)
 ///   The branches of the case distinction.
 ///
 /// ## Category
diff --git a/library/src/math/mod.rs b/library/src/math/mod.rs
index 5aeedf6f..105940c7 100644
--- a/library/src/math/mod.rs
+++ b/library/src/math/mod.rs
@@ -112,7 +112,7 @@ pub fn module() -> Module {
 /// Can be displayed inline with text or as a separate block.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// #set text("Latin Modern Roman")
 ///
 /// Let $a$, $b$, and $c$ be the side
@@ -129,13 +129,13 @@ pub fn module() -> Module {
 /// dollar signs to create a formula. Starting and ending the formula with at
 /// least one space lifts it into a separate block that is centered
 /// horizontally. For more details about math syntax, see the
-/// [main math page](/docs/reference/math).
+/// [main math page]($category/math).
 ///
 /// ## Parameters
-/// - body: Content (positional, required)
+/// - body: `Content` (positional, required)
 ///   The contents of the formula.
 ///
-/// - block: bool (named)
+/// - block: `bool` (named)
 ///   Whether the formula is displayed as a separate block.
 ///
 /// ## Category
diff --git a/library/src/math/op.rs b/library/src/math/op.rs
index 8cc007ea..4451477e 100644
--- a/library/src/math/op.rs
+++ b/library/src/math/op.rs
@@ -5,10 +5,18 @@ use super::*;
 /// # Text Operator
 /// A text operator in a math formula.
 ///
+/// ## Predefined Operators
+/// Typst predefines the operators `arccos`,  `arcsin`,  `arctan`,  `arg`,
+/// `cos`,  `cosh`,  `cot`,  `coth`,  `csc`,  `deg`,  `det`,  `dim`,  `exp`,
+/// `gcd`,  `hom`,  `mod`,  `inf`,  `ker`,  `lg`,  `lim`,  `ln`,  `log`,  `max`,
+/// `min`,  `Pr`,  `sec`,  `sin`,  `sinh`,  `sup`,  `tan`,  `tanh`,  `liminf`,
+/// and `limsup`.
+///
 /// ## Parameters
-/// - text: EcoString (positional, required)
+/// - text: `EcoString` (positional, required)
 ///   The operator's text.
-/// - limits: bool (named)
+///
+/// - limits: `bool` (named)
 ///   Whether the operator should force attachments to display as limits.
 ///
 ///   Defaults to `{false}`.
diff --git a/library/src/math/root.rs b/library/src/math/root.rs
index fa41167d..e40f56f0 100644
--- a/library/src/math/root.rs
+++ b/library/src/math/root.rs
@@ -4,12 +4,12 @@ use super::*;
 /// A square root.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// $ sqrt(x^2) = x = sqrt(x)^2 $
 /// ```
 ///
 /// ## Parameters
-/// - radicand: Content (positional, required)
+/// - radicand: `Content` (positional, required)
 ///   The expression to take the square root of.
 ///
 /// ## Category
@@ -36,15 +36,15 @@ impl LayoutMath for SqrtNode {
 /// A general root.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// $ root(3, x) $
 /// ```
 ///
 /// ## Parameters
-/// - index: Content (positional, required)
+/// - index: `Content` (positional, required)
 ///   Which root of the radicand to take.
 ///
-/// - radicand: Content (positional, required)
+/// - radicand: `Content` (positional, required)
 ///   The expression to take the root of.
 ///
 /// ## Category
diff --git a/library/src/math/style.rs b/library/src/math/style.rs
index 9e1f6699..9856a6b0 100644
--- a/library/src/math/style.rs
+++ b/library/src/math/style.rs
@@ -4,12 +4,12 @@ use super::*;
 /// Bold font style in math.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// $ bold(A) := B^+ $
 /// ```
 ///
 /// ## Parameters
-/// - body: Content (positional, required)
+/// - body: `Content` (positional, required)
 ///   The piece of formula to style.
 ///
 /// ## Category
@@ -39,12 +39,12 @@ impl LayoutMath for BoldNode {
 /// Upright (non-italic) font style in math.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// $ upright(A) != A $
 /// ```
 ///
 /// ## Parameters
-/// - body: Content (positional, required)
+/// - body: `Content` (positional, required)
 ///   The piece of formula to style.
 ///
 /// ## Category
@@ -76,7 +76,7 @@ impl LayoutMath for UprightNode {
 /// For roman letters and greek lowercase letters, this is already the default.
 ///
 /// ## Parameters
-/// - body: Content (positional, required)
+/// - body: `Content` (positional, required)
 ///   The piece of formula to style.
 ///
 /// ## Category
@@ -108,7 +108,7 @@ impl LayoutMath for ItalicNode {
 /// This is already the default.
 ///
 /// ## Parameters
-/// - body: Content (positional, required)
+/// - body: `Content` (positional, required)
 ///   The piece of formula to style.
 ///
 /// ## Category
@@ -138,12 +138,12 @@ impl LayoutMath for SerifNode {
 /// Sans-serif font style in math.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// $ sans(A B C) $
 /// ```
 ///
 /// ## Parameters
-/// - body: Content (positional, required)
+/// - body: `Content` (positional, required)
 ///   The piece of formula to style.
 ///
 /// ## Category
@@ -173,12 +173,12 @@ impl LayoutMath for SansNode {
 /// Calligraphic font style in math.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// Let $cal(P)$ be the set of ...
 /// ```
 ///
 /// ## Parameters
-/// - body: Content (positional, required)
+/// - body: `Content` (positional, required)
 ///   The piece of formula to style.
 ///
 /// ## Category
@@ -208,12 +208,12 @@ impl LayoutMath for CalNode {
 /// Fraktur font style in math.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// $ frak(P) $
 /// ```
 ///
 /// ## Parameters
-/// - body: Content (positional, required)
+/// - body: `Content` (positional, required)
 ///   The piece of formula to style.
 ///
 /// ## Category
@@ -243,12 +243,12 @@ impl LayoutMath for FrakNode {
 /// Monospace font style in math.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// $ mono(x + y = z) $
 /// ```
 ///
 /// ## Parameters
-/// - body: Content (positional, required)
+/// - body: `Content` (positional, required)
 ///   The piece of formula to style.
 ///
 /// ## Category
@@ -278,17 +278,18 @@ impl LayoutMath for MonoNode {
 /// Blackboard bold (double-struck) font style in math.
 ///
 /// For uppercase latin letters, blackboard bold is additionally available
-/// through [symbols](/docs/reference/math/symbols) of the form `NN` and `RR`.
+/// through [symbols]($category/symbols/sym) of the form `NN` and `RR`.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// $ bb(b) $
 /// $ bb(N) = NN $
 /// $ f: NN -> RR $
 /// ```
 ///
 /// ## Parameters
-/// - body: Content (positional, required) The piece of formula to style.
+/// - body: `Content` (positional, required)
+///   The piece of formula to style.
 ///
 /// ## Category
 /// math
diff --git a/library/src/math/underover.rs b/library/src/math/underover.rs
index a1c27e59..4387de20 100644
--- a/library/src/math/underover.rs
+++ b/library/src/math/underover.rs
@@ -8,12 +8,12 @@ const BRACKET_GAP: Em = Em::new(0.25);
 /// A horizontal line under content.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// $ underline(1 + 2 + ... + 5) $
 /// ```
 ///
 /// ## Parameters
-/// - body: Content (positional, required)
+/// - body: `Content` (positional, required)
 ///   The content above the line.
 ///
 /// ## Category
@@ -40,12 +40,12 @@ impl LayoutMath for UnderlineNode {
 /// A horizontal line over content.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// $ overline(1 + 2 + ... + 5) $
 /// ```
 ///
 /// ## Parameters
-/// - body: Content (positional, required)
+/// - body: `Content` (positional, required)
 ///   The content below the line.
 ///
 /// ## Category
@@ -72,15 +72,15 @@ impl LayoutMath for OverlineNode {
 /// A horizontal brace under content, with an optional annotation below.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// $ underbrace(1 + 2 + ... + 5, "numbers") $
 /// ```
 ///
 /// ## Parameters
-/// - body: Content (positional, required)
+/// - body: `Content` (positional, required)
 ///   The content above the brace.
 ///
-/// - annotation: Content (positional)
+/// - annotation: `Content` (positional)
 ///   The optional content below the brace.
 ///
 /// ## Category
@@ -114,15 +114,15 @@ impl LayoutMath for UnderbraceNode {
 /// A horizontal brace over content, with an optional annotation above.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// $ overbrace(1 + 2 + ... + 5, "numbers") $
 /// ```
 ///
 /// ## Parameters
-/// - body: Content (positional, required)
+/// - body: `Content` (positional, required)
 ///   The content below the brace.
 ///
-/// - annotation: Content (positional)
+/// - annotation: `Content` (positional)
 ///   The optional content above the brace.
 ///
 /// ## Category
@@ -156,15 +156,15 @@ impl LayoutMath for OverbraceNode {
 /// A horizontal bracket under content, with an optional annotation below.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// $ underbracket(1 + 2 + ... + 5, "numbers") $
 /// ```
 ///
 /// ## Parameters
-/// - body: Content (positional, required)
+/// - body: `Content` (positional, required)
 ///   The content above the bracket.
 ///
-/// - annotation: Content (positional)
+/// - annotation: `Content` (positional)
 ///   The optional content below the bracket.
 ///
 /// ## Category
@@ -198,15 +198,15 @@ impl LayoutMath for UnderbracketNode {
 /// A horizontal bracket over content, with an optional annotation above.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// $ overbracket(1 + 2 + ... + 5, "numbers") $
 /// ```
 ///
 /// ## Parameters
-/// - body: Content (positional, required)
+/// - body: `Content` (positional, required)
 ///   The content below the bracket.
 ///
-/// - annotation: Content (positional)
+/// - annotation: `Content` (positional)
 ///   The optional content above the bracket.
 ///
 /// ## Category