Make Rust happier about the inline documentation

5 files changed, 78 insertions, 88 deletions

diff --git a/library/src/basics/enum.rs b/library/src/basics/enum.rs
index c5d4d8ae..2bff7133 100644
--- a/library/src/basics/enum.rs
+++ b/library/src/basics/enum.rs
@@ -9,20 +9,8 @@ use crate::prelude::*;
 ///
 /// Displays a sequence of items vertically and numbers them consecutively.
 ///
-/// ## Syntax
-/// This functions also has dedicated syntax:
-///
-/// - Starting a line with a plus sign creates an automatically numbered
-///   enumeration item.
-/// - Start a line with a number followed by a dot creates an explicitly
-///   numbered enumeration item.
-///
-/// Enumeration items can contain multiple paragraphs and other block-level
-/// content. All content that is indented more than an item's plus sign or dot
-/// becomes part of that item.
-///
 /// ## Example
-/// ```
+/// ```example
 /// Automatically numbered:
 /// + Preparations
 /// + Analysis
@@ -37,15 +25,26 @@ use crate::prelude::*;
 /// #enum[First][Second]
 /// ```
 ///
+/// ## Syntax
+/// This functions also has dedicated syntax:
+///
+/// - Starting a line with a plus sign creates an automatically numbered
+///   enumeration item.
+/// - Start a line with a number followed by a dot creates an explicitly
+///   numbered enumeration item.
+///
+/// Enumeration items can contain multiple paragraphs and other block-level
+/// content. All content that is indented more than an item's plus sign or dot
+/// becomes part of that item.
+///
 /// ## Parameters
-/// - items: Content (positional, variadic)
+/// - items: `Content` (positional, variadic)
 ///   The enumeration's children.
 ///
 ///   When using the enum syntax, adjacent items are automatically collected
 ///   into enumerations, even through constructs like for loops.
 ///
-///   ### Example
-///   ```
+///   ```example
 ///   #for phase in (
 ///      "Launch",
 ///      "Orbit",
@@ -53,11 +52,10 @@ use crate::prelude::*;
 ///   ) [+ #phase]
 ///   ```
 ///
-/// - start: NonZeroUsize (named)
+/// - start: `NonZeroUsize` (named)
 ///   Which number to start the enumeration with.
 ///
-///   ### Example
-///   ```
+///   ```example
 ///   #enum(
 ///     start: 3,
 ///     [Skipping],
@@ -65,14 +63,13 @@ use crate::prelude::*;
 ///   )
 ///   ```
 ///
-/// - tight: bool (named)
+/// - tight: `bool` (named)
 ///   If this is `{false}`, the items are spaced apart with
-///   [enum spacing](@enum/spacing). If it is `{true}`, they use normal
-///   [leading](@par/leading) instead. This makes the enumeration more compact,
-///   which can look better if the items are short.
+///   [enum spacing]($func/enum.spacing). If it is `{true}`, they use normal
+///   [leading]($func/par.leading) instead. This makes the enumeration more
+///   compact, which can look better if the items are short.
 ///
-///   ### Example
-///   ```
+///   ```example
 ///   + If an enum has a lot of text, and
 ///     maybe other inline content, it
 ///     should not be tight anymore.
@@ -97,10 +94,9 @@ pub struct EnumNode {
 #[node]
 impl EnumNode {
     /// How to number the enumeration. Accepts a
-    /// [numbering pattern or function](@numbering).
+    /// [numbering pattern or function]($func/numbering).
     ///
-    /// # Example
-    /// ```
+    /// ```example
     /// #set enum(numbering: "(a)")
     ///
     /// + Different
@@ -121,7 +117,7 @@ impl EnumNode {
 
     /// The spacing between the items of a wide (non-tight) enumeration.
     ///
-    /// If set to `{auto}` uses the spacing [below blocks](@block/below).
+    /// If set to `{auto}` uses the spacing [below blocks]($func/block.below).
     pub const SPACING: Smart<Spacing> = Smart::Auto;
 
     fn construct(_: &Vm, args: &mut Args) -> SourceResult<Content> {
diff --git a/library/src/basics/heading.rs b/library/src/basics/heading.rs
index c2696dd6..7ae76920 100644
--- a/library/src/basics/heading.rs
+++ b/library/src/basics/heading.rs
@@ -16,14 +16,15 @@ use crate::text::{SpaceNode, TextNode, TextSize};
 ///
 /// Typst can automatically number your headings for you. To enable numbering,
 /// specify how you want your headings to be numbered with a
-/// [numbering pattern or function](@numbering).
+/// [numbering pattern or function]($func/numbering).
 ///
 /// Independently from the numbering, Typst can also automatically generate an
-/// [outline](@outline) of all headings for you. To exclude one or more headings
-/// from this outline, you can set the `outlined` parameter to `{false}`.
+/// [outline]($func/outline) of all headings for you. To exclude one or more
+/// headings from this outline, you can set the `outlined` parameter to
+/// `{false}`.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// #set heading(numbering: "1.a)")
 ///
 /// = Introduction
@@ -39,10 +40,10 @@ use crate::text::{SpaceNode, TextNode, TextSize};
 /// signs determines the heading's logical nesting depth.
 ///
 /// ## Parameters
-/// - title: Content (positional, required)
+/// - title: `Content` (positional, required)
 ///   The heading's title.
 ///
-/// - level: NonZeroUsize (named)
+/// - level: `NonZeroUsize` (named)
 ///   The logical nesting depth of the heading, starting from one.
 ///
 /// ## Category
@@ -61,10 +62,9 @@ pub struct HeadingNode {
 #[node]
 impl HeadingNode {
     /// How to number the heading. Accepts a
-    /// [numbering pattern or function](@numbering).
+    /// [numbering pattern or function]($func/numbering).
     ///
-    /// # Example
-    /// ```
+    /// ```example
     /// #set heading(numbering: "1.a.")
     ///
     /// = A section
@@ -76,8 +76,7 @@ impl HeadingNode {
 
     /// Whether the heading should appear in the outline.
     ///
-    /// # Example
-    /// ```
+    /// ```example
     /// #outline()
     ///
     /// #heading[Normal]
diff --git a/library/src/basics/list.rs b/library/src/basics/list.rs
index 42cee4ed..4b9fdafb 100644
--- a/library/src/basics/list.rs
+++ b/library/src/basics/list.rs
@@ -8,14 +8,8 @@ use crate::text::TextNode;
 /// Displays a sequence of items vertically, with each item introduced by a
 /// marker.
 ///
-/// ## Syntax
-/// This functions also has dedicated syntax: Start a line with a hyphen,
-/// followed by a space to create a list item. A list item can contain multiple
-/// paragraphs and other block-level content. All content that is indented
-/// more than an item's hyphen becomes part of that item.
-///
 /// ## Example
-/// ```
+/// ```example
 /// - *Content*
 ///   - Basics
 ///   - Text
@@ -34,28 +28,32 @@ use crate::text::TextNode;
 ///   )
 /// ```
 ///
+/// ## Syntax
+/// This functions also has dedicated syntax: Start a line with a hyphen,
+/// followed by a space to create a list item. A list item can contain multiple
+/// paragraphs and other block-level content. All content that is indented
+/// more than an item's hyphen becomes part of that item.
+///
 /// ## Parameters
-/// - items: Content (positional, variadic)
+/// - items: `Content` (positional, variadic)
 ///   The list's children.
 ///
 ///   When using the list syntax, adjacent items are automatically collected
 ///   into lists, even through constructs like for loops.
 ///
-///   ### Example
-///   ```
+///   ```example
 ///   #for letter in "ABC" [
 ///     - Letter #letter
 ///   ]
 ///   ```
 ///
-/// - tight: bool (named)
-///   If this is `{false}`, the items are spaced apart with
-///   [list spacing](@list/spacing). If it is `{true}`, they use normal
-///   [leading](@par/leading) instead. This makes the list more compact, which
-///   can look better if the items are short.
+/// - tight: `bool` (named)
+///   If this is `{false}`, the items are spaced apart with [list
+///   spacing]($func/list.spacing). If it is `{true}`, they use normal
+///   [leading]($func/par.leading) instead. This makes the list more compact,
+///   which can look better if the items are short.
 ///
-///   ### Example
-///   ```
+///   ```example
 ///   - If a list has a lot of text, and
 ///     maybe other inline content, it
 ///     should not be tight anymore.
@@ -80,8 +78,7 @@ pub struct ListNode {
 impl ListNode {
     /// The marker which introduces each element.
     ///
-    /// # Example
-    /// ```
+    /// ```example
     /// #set list(marker: [--])
     ///
     /// - A more classic list
@@ -100,7 +97,7 @@ impl ListNode {
 
     /// The spacing between the items of a wide (non-tight) list.
     ///
-    /// If set to `{auto}` uses the spacing [below blocks](@block/below).
+    /// If set to `{auto}` uses the spacing [below blocks]($func/block.below).
     pub const SPACING: Smart<Spacing> = Smart::Auto;
 
     fn construct(_: &Vm, args: &mut Args) -> SourceResult<Content> {
diff --git a/library/src/basics/table.rs b/library/src/basics/table.rs
index 6ee2b0b2..56df2cea 100644
--- a/library/src/basics/table.rs
+++ b/library/src/basics/table.rs
@@ -7,11 +7,11 @@ use crate::prelude::*;
 /// Tables are used to arrange content in cells. Cells can contain arbitrary
 /// content, including multiple paragraphs and are specified in row-major order.
 /// Because tables are just grids with configurable cell properties, refer to
-/// the [grid documentation](@grid) for more information on how to size the
+/// the [grid documentation]($func/grid) for more information on how to size the
 /// table tracks.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// #table(
 ///   columns: (1fr, auto, auto),
 ///   inset: 10pt,
@@ -31,28 +31,30 @@ use crate::prelude::*;
 /// ```
 ///
 /// ## Parameters
-/// - cells: Content (positional, variadic)
+/// - cells: `Content` (positional, variadic)
 ///   The contents of the table cells.
 ///
-/// - rows: TrackSizings (named)
+/// - rows: `TrackSizings` (named)
 ///   Defines the row sizes.
-///   See the [grid documentation](@grid) for more information on track sizing.
+///   See the [grid documentation]($func/grid) for more information on track
+///   sizing.
 ///
-/// - columns: TrackSizings (named)
+/// - columns: `TrackSizings` (named)
 ///   Defines the column sizes.
-///   See the [grid documentation](@grid) for more information on track sizing.
+///   See the [grid documentation]($func/grid) for more information on track
+///   sizing.
 ///
-/// - gutter: TrackSizings (named)
+/// - gutter: `TrackSizings` (named)
 ///   Defines the gaps between rows & columns.
-///   See the [grid documentation](@grid) for more information on gutters.
+///   See the [grid documentation]($func/grid) for more information on gutters.
 ///
-/// - column-gutter: TrackSizings (named)
+/// - column-gutter: `TrackSizings` (named)
 ///   Defines the gaps between columns. Takes precedence over `gutter`.
-///   See the [grid documentation](@grid) for more information on gutters.
+///   See the [grid documentation]($func/grid) for more information on gutters.
 ///
-/// - row-gutter: TrackSizings (named)
+/// - row-gutter: `TrackSizings` (named)
 ///   Defines the gaps between rows. Takes precedence over `gutter`.
-///   See the [grid documentation](@grid) for more information on gutters.
+///   See the [grid documentation]($func/grid) for more information on gutters.
 ///
 /// ## Category
 /// basics
@@ -76,8 +78,7 @@ impl TableNode {
     /// passed the cell's column and row index, starting at zero. This can be
     /// used to implement striped tables.
     ///
-    /// # Example
-    /// ```
+    /// ```example
     /// #table(
     ///   fill: (col, _) => if calc.odd(col) { luma(240) } else { white },
     ///   align: (col, row) =>
diff --git a/library/src/basics/terms.rs b/library/src/basics/terms.rs
index 1409350a..2e52c87d 100644
--- a/library/src/basics/terms.rs
+++ b/library/src/basics/terms.rs
@@ -14,21 +14,20 @@ use crate::text::{SpaceNode, TextNode};
 /// followed by a term, a colon and a description creates a term list item.
 ///
 /// ## Example
-/// ```
+/// ```example
 /// / Ligature: A merged glyph.
 /// / Kerning: A spacing adjustment
 ///   between two adjacent letters.
 /// ```
 ///
 /// ## Parameters
-/// - items: Content (positional, variadic)
+/// - items: `Content` (positional, variadic)
 ///   The term list's children.
 ///
 ///   When using the term list syntax, adjacent items are automatically
 ///   collected into term lists, even through constructs like for loops.
 ///
-///   ### Example
-///   ```
+///   ```example
 ///   #for year, product in (
 ///     "1978": "TeX",
 ///     "1984": "LaTeX",
@@ -36,14 +35,13 @@ use crate::text::{SpaceNode, TextNode};
 ///   ) [/ #product: Born in #year.]
 ///   ```
 ///
-/// - tight: bool (named)
+/// - tight: `bool` (named)
 ///   If this is `{false}`, the items are spaced apart with [term list
-///   spacing](@terms/spacing). If it is `{true}`, they use normal
-///   [leading](@par/leading) instead. This makes the term list more compact,
-///   which can look better if the items are short.
+///   spacing]($func/terms.spacing). If it is `{true}`, they use normal
+///   [leading]($func/par.leading) instead. This makes the term list more
+///   compact, which can look better if the items are short.
 ///
-///   ### Example
-///   ```
+///   ```example
 ///   / Fact: If a term list has a lot
 ///     of text, and maybe other inline
 ///     content, it should not be tight
@@ -74,8 +72,7 @@ impl TermsNode {
 
     /// The hanging indent of the description.
     ///
-    /// # Example
-    /// ```
+    /// ```example
     /// #set terms(hanging-indent: 0pt)
     /// / Term: This term list does not
     ///   make use of hanging indents.
@@ -85,7 +82,7 @@ impl TermsNode {
 
     /// The spacing between the items of a wide (non-tight) term list.
     ///
-    /// If set to `{auto}` uses the spacing [below blocks](@block/below).
+    /// If set to `{auto}` uses the spacing [below blocks]($func/block.below).
     pub const SPACING: Smart<Spacing> = Smart::Auto;
 
     fn construct(_: &Vm, args: &mut Args) -> SourceResult<Content> {