Formatting and documentation ✨

8 files changed, 118 insertions, 79 deletions

diff --git a/src/library/align.rs b/src/library/align.rs
index 31367a5a..a516ff4c 100644
--- a/src/library/align.rs
+++ b/src/library/align.rs
@@ -2,26 +2,30 @@ use super::*;
 
 /// `align`: Align content along the layouting axes.
 ///
+/// # Positional parameters
+/// - Alignments: variadic, of type `alignment`.
+/// - Body: optional, of type `template`.
+///
 /// Which axis an alignment should apply to (main or cross) is inferred from
 /// either the argument itself (for anything other than `center`) or from the
 /// second argument if present, defaulting to the cross axis for a single
 /// `center` alignment.
 ///
-/// # Positional arguments
-/// - Alignments: variadic, of type `alignment`.
-/// - Body:       optional, of type `template`.
-///
-/// # Named arguments
+/// # Named parameters
 /// - Horizontal alignment: `horizontal`, of type `alignment`.
-/// - Vertical alignment:   `vertical`, of type `alignment`.
+/// - Vertical alignment: `vertical`, of type `alignment`.
+///
+/// # Return value
+/// A template that changes the alignment along the layouting axes. The effect
+/// is scoped to the body if present.
 ///
 /// # Relevant types and constants
 /// - Type `alignment`
-///     - `left`
-///     - `right`
-///     - `top`
-///     - `bottom`
-///     - `center`
+///   - `left`
+///   - `right`
+///   - `top`
+///   - `bottom`
+///   - `center`
 pub fn align(ctx: &mut EvalContext, args: &mut ValueArgs) -> Value {
     let first = args.find(ctx);
     let second = args.find(ctx);
diff --git a/src/library/base.rs b/src/library/base.rs
index 3d067faa..4d36b878 100644
--- a/src/library/base.rs
+++ b/src/library/base.rs
@@ -5,7 +5,7 @@ use super::*;
 
 /// `repr`: Get the string representation of a value.
 ///
-/// # Positional arguments
+/// # Positional parameters
 /// - Any value.
 ///
 /// # Return value
@@ -19,11 +19,14 @@ pub fn repr(ctx: &mut EvalContext, args: &mut ValueArgs) -> Value {
 
 /// `rgb`: Create an RGB(A) color.
 ///
-/// # Positional arguments
-/// - Red component:   of type `float`, between 0.0 and 1.0.
+/// # Positional parameters
+/// - Red component: of type `float`, between 0.0 and 1.0.
 /// - Green component: of type `float`, between 0.0 and 1.0.
-/// - Blue component:  of type `float`, between 0.0 and 1.0.
+/// - Blue component: of type `float`, between 0.0 and 1.0.
 /// - Alpha component: optional, of type `float`, between 0.0 and 1.0.
+///
+/// # Return value
+/// The color with the given components.
 pub fn rgb(ctx: &mut EvalContext, args: &mut ValueArgs) -> Value {
     let r = args.require(ctx, "red component");
     let g = args.require(ctx, "green component");
@@ -49,7 +52,7 @@ pub fn rgb(ctx: &mut EvalContext, args: &mut ValueArgs) -> Value {
 
 /// `type`: Find out the name of a value's type.
 ///
-/// # Positional arguments
+/// # Positional parameters
 /// - Any value.
 ///
 /// # Return value
diff --git a/src/library/font.rs b/src/library/font.rs
index 79cc8518..460cfba1 100644
--- a/src/library/font.rs
+++ b/src/library/font.rs
@@ -4,44 +4,48 @@ use super::*;
 
 /// `font`: Configure the font.
 ///
-/// # Positional arguments
-/// - Font size:     optional, of type `linear` relative to current font size.
+/// # Positional parameters
+/// - Font size: optional, of type `linear` relative to current font size.
 /// - Font families: variadic, of type `font-family`.
-/// - Body:          optional, of type `template`.
+/// - Body: optional, of type `template`.
 ///
-/// # Named arguments
-/// - Font Style:                   `style`, of type `font-style`.
-/// - Font Weight:                  `weight`, of type `font-weight`.
-/// - Serif family definition:      `serif`, of type `font-families`.
-/// - Sans-serif family definition: `sans-serif`, of type `font-families`.
-/// - Monospace family definition:  `monospace`, of type `font-families`.
-/// - Font Stretch:                 `stretch`, of type `relative`, between 0.5 and 2.0.
+/// # Named parameters
+/// - Font Style: `style`, of type `font-style`.
+/// - Font Weight: `weight`, of type `font-weight`.
+/// - Font Stretch: `stretch`, of type `relative`, between 0.5 and 2.0.
+/// - Serif family definition: `serif`, of type `font-familiy-list`.
+/// - Sans-serif family definition: `sans-serif`, of type `font-familiy-list`.
+/// - Monospace family definition: `monospace`, of type `font-familiy-list`.
+///
+/// # Return value
+/// A template that configures font properties. The effect is scoped to the body
+/// if present.
 ///
 /// # Relevant types and constants
-/// - Type `font-families`
-///     - coerces from `string`
-///     - coerces from `array`
-///     - coerces from `font-family`
+/// - Type `font-family-list`
+///   - coerces from `string`
+///   - coerces from `array`
+///   - coerces from `font-family`
 /// - Type `font-family`
-///     - `serif`
-///     - `sans-serif`
-///     - `monospace`
-///     - coerces from `string`
+///   - `serif`
+///   - `sans-serif`
+///   - `monospace`
+///   - coerces from `string`
 /// - Type `font-style`
-///     - `normal`
-///     - `italic`
-///     - `oblique`
+///   - `normal`
+///   - `italic`
+///   - `oblique`
 /// - Type `font-weight`
-///     - `thin` (100)
-///     - `extralight` (200)
-///     - `light` (300)
-///     - `regular` (400)
-///     - `medium` (500)
-///     - `semibold` (600)
-///     - `bold` (700)
-///     - `extrabold` (800)
-///     - `black` (900)
-///     - coerces from `integer`
+///   - `thin` (100)
+///   - `extralight` (200)
+///   - `light` (300)
+///   - `regular` (400)
+///   - `medium` (500)
+///   - `semibold` (600)
+///   - `bold` (700)
+///   - `extrabold` (800)
+///   - `black` (900)
+///   - coerces from `integer`
 pub fn font(ctx: &mut EvalContext, args: &mut ValueArgs) -> Value {
     let size = args.find::<Linear>(ctx);
     let list: Vec<_> = args.filter::<FontFamily>(ctx).map(|f| f.to_string()).collect();
diff --git a/src/library/image.rs b/src/library/image.rs
index d9c0a0a7..c3200e93 100644
--- a/src/library/image.rs
+++ b/src/library/image.rs
@@ -8,8 +8,11 @@ use crate::layout::*;
 ///
 /// Supports PNG and JPEG files.
 ///
-/// # Positional arguments
+/// # Positional parameters
 /// - Path to image file: of type `string`.
+///
+/// # Return value
+/// A template that inserts an image.
 pub fn image(ctx: &mut EvalContext, args: &mut ValueArgs) -> Value {
     let path = args.require::<Spanned<String>>(ctx, "path to image file");
     let width = args.get(ctx, "width");
diff --git a/src/library/pad.rs b/src/library/pad.rs
index ba28bf8e..5d59f2b3 100644
--- a/src/library/pad.rs
+++ b/src/library/pad.rs
@@ -2,15 +2,18 @@ use super::*;
 
 /// `pad`: Pad content at the sides.
 ///
-/// # Positional arguments
+/// # Positional parameters
 /// - Padding for all sides: `padding`, of type `linear` relative to sides.
 /// - Body: of type `template`.
 ///
-/// # Named arguments
-/// - Left padding:   `left`, of type `linear` relative to parent width.
-/// - Right padding:  `right`, of type `linear` relative to parent width.
-/// - Top padding:    `top`, of type `linear` relative to parent height.
+/// # Named parameters
+/// - Left padding: `left`, of type `linear` relative to parent width.
+/// - Right padding: `right`, of type `linear` relative to parent width.
+/// - Top padding: `top`, of type `linear` relative to parent height.
 /// - Bottom padding: `bottom`, of type `linear` relative to parent height.
+///
+/// # Return value
+/// A template that pads the body at the sides.
 pub fn pad(ctx: &mut EvalContext, args: &mut ValueArgs) -> Value {
     let all = args.find(ctx);
     let left = args.get(ctx, "left");
diff --git a/src/library/page.rs b/src/library/page.rs
index 20d7f069..17021607 100644
--- a/src/library/page.rs
+++ b/src/library/page.rs
@@ -3,22 +3,33 @@ use crate::paper::{Paper, PaperClass};
 
 /// `page`: Configure pages.
 ///
-/// # Positional arguments
+/// # Positional parameters
 /// - Paper name: optional, of type `string`, see [here](crate::paper) for a
-///               full list of all paper names.
-/// - Body:       optional, of type `template`.
+///   full list of all paper names.
+/// - Body: optional, of type `template`.
 ///
-/// # Named arguments
-/// - Width of the page:         `width`, of type `length`.
-/// - Height of the page:        `height`, of type `length`.
-/// - Margins for all sides:     `margins`, of type `linear` relative to sides.
-/// - Left margin:               `left`, of type `linear` relative to width.
-/// - Right margin:              `right`, of type `linear` relative to width.
-/// - Top margin:                `top`, of type `linear` relative to height.
-/// - Bottom margin:             `bottom`, of type `linear` relative to height.
-/// - Flip width and height:     `flip`, of type `bool`.
-/// - Main layouting direction:  `main-dir`, of type `direction`.
+/// # Named parameters
+/// - Width of the page: `width`, of type `length`.
+/// - Height of the page: `height`, of type `length`.
+/// - Margins for all sides: `margins`, of type `linear` relative to sides.
+/// - Left margin: `left`, of type `linear` relative to width.
+/// - Right margin: `right`, of type `linear` relative to width.
+/// - Top margin: `top`, of type `linear` relative to height.
+/// - Bottom margin: `bottom`, of type `linear` relative to height.
+/// - Flip width and height: `flip`, of type `bool`.
+/// - Main layouting direction: `main-dir`, of type `direction`.
 /// - Cross layouting direction: `cross-dir`, of type `direction`.
+///
+/// # Return value
+/// A template that configures page properties. The effect is scoped to the body
+/// if present.
+///
+/// # Relevant types and constants
+/// - Type `direction`
+///   - `ltr` (left to right)
+///   - `rtl` (right to left)
+///   - `ttb` (top to bottom)
+///   - `btt` (bottom to top)
 pub fn page(ctx: &mut EvalContext, args: &mut ValueArgs) -> Value {
     let paper = args.find::<Spanned<String>>(ctx).and_then(|name| {
         Paper::from_name(&name.v).or_else(|| {
@@ -96,6 +107,9 @@ pub fn page(ctx: &mut EvalContext, args: &mut ValueArgs) -> Value {
 }
 
 /// `pagebreak`: Start a new page.
+///
+/// # Return value
+/// A template that starts a new page.
 pub fn pagebreak(_: &mut EvalContext, args: &mut ValueArgs) -> Value {
     let span = args.span;
     Value::template("pagebreak", move |ctx| {
diff --git a/src/library/shapes.rs b/src/library/shapes.rs
index 41be3b2b..48bc7ebd 100644
--- a/src/library/shapes.rs
+++ b/src/library/shapes.rs
@@ -2,22 +2,25 @@ use super::*;
 
 /// `rect`: Create a rectangular box.
 ///
-/// # Positional arguments
+/// # Positional parameters
 /// - Body: optional, of type `template`.
 ///
-/// # Named arguments
-/// - Width of the box:          `width`, of type `linear` relative to parent width.
-/// - Height of the box:         `height`, of type `linear` relative to parent height.
-/// - Main layouting direction:  `main-dir`, of type `direction`.
+/// # Named parameters
+/// - Width of the box: `width`, of type `linear` relative to parent width.
+/// - Height of the box: `height`, of type `linear` relative to parent height.
+/// - Main layouting direction: `main-dir`, of type `direction`.
 /// - Cross layouting direction: `cross-dir`, of type `direction`.
-/// - Fill color of the box:     `fill`, of type `color`.
+/// - Fill color of the box: `fill`, of type `color`.
+///
+/// # Return value
+/// A template that places the body into a rectangle.
 ///
 /// # Relevant types and constants
 /// - Type `direction`
-///     - `ltr` (left to right)
-///     - `rtl` (right to left)
-///     - `ttb` (top to bottom)
-///     - `btt` (bottom to top)
+///   - `ltr` (left to right)
+///   - `rtl` (right to left)
+///   - `ttb` (top to bottom)
+///   - `btt` (bottom to top)
 pub fn rect(ctx: &mut EvalContext, args: &mut ValueArgs) -> Value {
     let width = args.get(ctx, "width");
     let height = args.get(ctx, "height");
diff --git a/src/library/spacing.rs b/src/library/spacing.rs
index 3cc718b2..d8f18f41 100644
--- a/src/library/spacing.rs
+++ b/src/library/spacing.rs
@@ -2,16 +2,22 @@ use super::*;
 
 /// `h`: Add horizontal spacing.
 ///
-/// # Positional arguments
+/// # Positional parameters
 /// - Amount of spacing: of type `linear` relative to current font size.
+///
+/// # Return value
+/// A template that adds horizontal spacing.
 pub fn h(ctx: &mut EvalContext, args: &mut ValueArgs) -> Value {
     spacing(ctx, args, SpecAxis::Horizontal)
 }
 
 /// `v`: Add vertical spacing.
 ///
-/// # Positional arguments
+/// # Positional parameters
 /// - Amount of spacing: of type `linear` relative to current font size.
+///
+/// # Return value
+/// A template that adds vertical spacing.
 pub fn v(ctx: &mut EvalContext, args: &mut ValueArgs) -> Value {
     spacing(ctx, args, SpecAxis::Vertical)
 }
@@ -19,7 +25,6 @@ pub fn v(ctx: &mut EvalContext, args: &mut ValueArgs) -> Value {
 /// Apply spacing along a specific axis.
 fn spacing(ctx: &mut EvalContext, args: &mut ValueArgs, axis: SpecAxis) -> Value {
     let spacing: Option<Linear> = args.require(ctx, "spacing");
-
     Value::template("spacing", move |ctx| {
         if let Some(linear) = spacing {
             let amount = linear.resolve(ctx.state.font.font_size());