Document parameters in comment

5 files changed, 250 insertions, 83 deletions

diff --git a/library/src/compute/calc.rs b/library/src/compute/calc.rs
index 62d0a419..eccc4531 100644
--- a/library/src/compute/calc.rs
+++ b/library/src/compute/calc.rs
@@ -4,26 +4,37 @@ use crate::prelude::*;
 
 /// The absolute value of a numeric value.
 ///
-/// Tags: calculate.
+/// # Parameters
+/// - value: ToAbs (positional, required)
+///   The value whose absolute value to calculate.
+///
+/// # Tags
+/// - calculate
 #[func]
 pub fn abs(args: &mut Args) -> SourceResult<Value> {
-    let Spanned { v, span } = args.expect("numeric value")?;
-    Ok(match v {
-        Value::Int(v) => Value::Int(v.abs()),
-        Value::Float(v) => Value::Float(v.abs()),
-        Value::Angle(v) => Value::Angle(v.abs()),
-        Value::Ratio(v) => Value::Ratio(v.abs()),
-        Value::Fraction(v) => Value::Fraction(v.abs()),
-        Value::Length(_) | Value::Relative(_) => {
-            bail!(span, "cannot take absolute value of a length")
-        }
-        v => bail!(span, "expected numeric value, found {}", v.type_name()),
-    })
+    Ok(args.expect::<ToAbs>("value")?.0)
+}
+
+/// A value of which the absolute value can be taken.
+struct ToAbs(Value);
+
+castable! {
+    ToAbs,
+    v: i64 => Self(Value::Int(v.abs())),
+    v: f64 => Self(Value::Float(v.abs())),
+    v: Angle => Self(Value::Angle(v.abs())),
+    v: Ratio => Self(Value::Ratio(v.abs())),
+    v: Fr => Self(Value::Fraction(v.abs())),
 }
 
 /// The minimum of a sequence of values.
 ///
-/// Tags: calculate.
+/// # Parameters
+/// - values: Value (positional, variadic)
+///   The sequence of values.
+///
+/// # Tags
+/// - calculate
 #[func]
 pub fn min(args: &mut Args) -> SourceResult<Value> {
     minmax(args, Ordering::Less)
@@ -31,7 +42,12 @@ pub fn min(args: &mut Args) -> SourceResult<Value> {
 
 /// The maximum of a sequence of values.
 ///
-/// Tags: calculate.
+/// # Parameters
+/// - values: Value (positional, variadic)
+///   The sequence of values.
+///
+/// # Tags
+/// - calculate
 #[func]
 pub fn max(args: &mut Args) -> SourceResult<Value> {
     minmax(args, Ordering::Greater)
@@ -60,27 +76,44 @@ fn minmax(args: &mut Args, goal: Ordering) -> SourceResult<Value> {
 
 /// Whether an integer is even.
 ///
-/// Tags: calculate.
+/// # Parameters
+/// - value: i64 (positional, required)
+///   The number to check for evenness.
+///
+/// # Tags
+/// - calculate
 #[func]
 pub fn even(args: &mut Args) -> SourceResult<Value> {
-    Ok(Value::Bool(args.expect::<i64>("integer")? % 2 == 0))
+    Ok(Value::Bool(args.expect::<i64>("value")? % 2 == 0))
 }
 
 /// Whether an integer is odd.
 ///
-/// Tags: calculate.
+/// # Parameters
+/// - value: i64 (positional, required)
+///   The number to check for oddness.
+///
+/// # Tags
+/// - calculate
 #[func]
 pub fn odd(args: &mut Args) -> SourceResult<Value> {
-    Ok(Value::Bool(args.expect::<i64>("integer")? % 2 != 0))
+    Ok(Value::Bool(args.expect::<i64>("value")? % 2 != 0))
 }
 
-/// The modulo of two numbers.
+/// The modulus of two numbers.
+///
+/// # Parameters
+/// - dividend: ToMod (positional, required)
+///   The dividend of the modulus.
+/// - divisor: ToMod (positional, required)
+///   The divisor of the modulus.
 ///
-/// Tags: calculate.
+/// # Tags
+/// - calculate
 #[func]
 pub fn mod_(args: &mut Args) -> SourceResult<Value> {
-    let Spanned { v: v1, span: span1 } = args.expect("integer or float")?;
-    let Spanned { v: v2, span: span2 } = args.expect("integer or float")?;
+    let Spanned { v: v1, span: span1 } = args.expect("dividend")?;
+    let Spanned { v: v2, span: span2 } = args.expect("divisor")?;
 
     let (a, b) = match (v1, v2) {
         (Value::Int(a), Value::Int(b)) => match a.checked_rem(b) {
@@ -104,3 +137,12 @@ pub fn mod_(args: &mut Args) -> SourceResult<Value> {
 
     Ok(Value::Float(a % b))
 }
+
+/// A value which can be passed to the `mod` function.
+struct ToMod;
+
+castable! {
+    ToMod,
+    _: i64 => Self,
+    _: f64 => Self,
+}
diff --git a/library/src/compute/create.rs b/library/src/compute/create.rs
index a0eecfb8..e3733d60 100644
--- a/library/src/compute/create.rs
+++ b/library/src/compute/create.rs
@@ -6,42 +6,60 @@ use crate::prelude::*;
 
 /// Convert a value to an integer.
 ///
-/// Tags: create.
+/// # Parameters
+/// - value: ToInt (positional, required)
+///   The value that should be converted to an integer.
+///
+/// # Tags
+/// - create
 #[func]
 pub fn int(args: &mut Args) -> SourceResult<Value> {
-    let Spanned { v, span } = args.expect("value")?;
-    Ok(Value::Int(match v {
-        Value::Bool(v) => v as i64,
-        Value::Int(v) => v,
-        Value::Float(v) => v as i64,
-        Value::Str(v) => match v.parse() {
-            Ok(v) => v,
-            Err(_) => bail!(span, "invalid integer"),
-        },
-        v => bail!(span, "cannot convert {} to integer", v.type_name()),
-    }))
+    Ok(Value::Int(args.expect::<ToInt>("value")?.0))
+}
+
+/// A value that can be cast to an integer.
+struct ToInt(i64);
+
+castable! {
+    ToInt,
+    v: bool => Self(v as i64),
+    v: i64 => Self(v),
+    v: f64 => Self(v as i64),
+    v: EcoString => Self(v.parse().map_err(|_| "not a valid integer")?),
 }
 
 /// Convert a value to a float.
 ///
-/// Tags: create.
+/// # Parameters
+/// - value: ToFloat (positional, required)
+///   The value that should be converted to a float.
+///
+/// # Tags
+/// - create
 #[func]
 pub fn float(args: &mut Args) -> SourceResult<Value> {
-    let Spanned { v, span } = args.expect("value")?;
-    Ok(Value::Float(match v {
-        Value::Int(v) => v as f64,
-        Value::Float(v) => v,
-        Value::Str(v) => match v.parse() {
-            Ok(v) => v,
-            Err(_) => bail!(span, "invalid float"),
-        },
-        v => bail!(span, "cannot convert {} to float", v.type_name()),
-    }))
+    Ok(Value::Float(args.expect::<ToFloat>("value")?.0))
+}
+
+/// A value that can be cast to a float.
+struct ToFloat(f64);
+
+castable! {
+    ToFloat,
+    v: bool => Self(v as i64 as f64),
+    v: i64 => Self(v as f64),
+    v: f64 => Self(v),
+    v: EcoString => Self(v.parse().map_err(|_| "not a valid float")?),
 }
 
 /// Create a grayscale color.
 ///
-/// Tags: create.
+/// # Parameters
+/// - gray: Component (positional, required)
+///   The gray component.
+///
+/// # Tags
+/// - create
 #[func]
 pub fn luma(args: &mut Args) -> SourceResult<Value> {
     let Component(luma) = args.expect("gray component")?;
@@ -50,7 +68,26 @@ pub fn luma(args: &mut Args) -> SourceResult<Value> {
 
 /// Create an RGB(A) color.
 ///
-/// Tags: create.
+/// # Parameters
+/// - hex: EcoString (positional)
+///   The color in hexademical notation.
+///
+///   Accepts three, four, six or eight hexadecimal digits and optionally
+///   a leading hashtag.
+///
+///   If this string is given, the individual components should not be given.
+///
+/// - red: Component (positional)
+///   The red component.
+/// - green: Component (positional)
+///   The green component.
+/// - blue: Component (positional)
+///   The blue component.
+/// - alpha: Component (positional)
+///   The alpha component.
+///
+/// # Tags
+/// - create
 #[func]
 pub fn rgb(args: &mut Args) -> SourceResult<Value> {
     Ok(Value::Color(if let Some(string) = args.find::<Spanned<EcoString>>()? {
@@ -67,18 +104,6 @@ pub fn rgb(args: &mut Args) -> SourceResult<Value> {
     }))
 }
 
-/// Create a CMYK color.
-///
-/// Tags: create.
-#[func]
-pub fn cmyk(args: &mut Args) -> SourceResult<Value> {
-    let RatioComponent(c) = args.expect("cyan component")?;
-    let RatioComponent(m) = args.expect("magenta component")?;
-    let RatioComponent(y) = args.expect("yellow component")?;
-    let RatioComponent(k) = args.expect("key component")?;
-    Ok(Value::Color(CmykColor::new(c, m, y, k).into()))
-}
-
 /// An integer or ratio component.
 struct Component(u8);
 
@@ -95,6 +120,29 @@ castable! {
     },
 }
 
+/// Create a CMYK color.
+///
+/// # Parameters
+/// - cyan: RatioComponent (positional, required)
+///   The cyan component.
+/// - magenta: RatioComponent (positional, required)
+///   The magenta component.
+/// - yellow: RatioComponent (positional, required)
+///   The yellow component.
+/// - key: RatioComponent (positional, required)
+///   The key component.
+///
+/// # Tags
+/// - create
+#[func]
+pub fn cmyk(args: &mut Args) -> SourceResult<Value> {
+    let RatioComponent(c) = args.expect("cyan component")?;
+    let RatioComponent(m) = args.expect("magenta component")?;
+    let RatioComponent(y) = args.expect("yellow component")?;
+    let RatioComponent(k) = args.expect("key component")?;
+    Ok(Value::Color(CmykColor::new(c, m, y, k).into()))
+}
+
 /// A component that must be a ratio.
 struct RatioComponent(u8);
 
@@ -109,22 +157,36 @@ castable! {
 
 /// Convert a value to a string.
 ///
-/// Tags: create.
+/// # Parameters
+/// - value: ToStr (positional, required)
+///   The value that should be converted to a string.
+///
+/// # Tags
+/// - create
 #[func]
 pub fn str(args: &mut Args) -> SourceResult<Value> {
-    let Spanned { v, span } = args.expect("value")?;
-    Ok(Value::Str(match v {
-        Value::Int(v) => format_str!("{}", v),
-        Value::Float(v) => format_str!("{}", v),
-        Value::Label(label) => label.0.into(),
-        Value::Str(v) => v,
-        v => bail!(span, "cannot convert {} to string", v.type_name()),
-    }))
+    Ok(Value::Str(args.expect::<ToStr>("value")?.0))
+}
+
+/// A value that can be cast to a string.
+struct ToStr(Str);
+
+castable! {
+    ToStr,
+    v: i64 => Self(format_str!("{}", v)),
+    v: f64 => Self(format_str!("{}", v)),
+    v: Label => Self(v.0.into()),
+    v: Str => Self(v),
 }
 
 /// Create a label from a string.
 ///
-/// Tags: create.
+/// # Parameters
+/// - name: EcoString (positional, required)
+///   The name of the label.
+///
+/// # Tags
+/// - create
 #[func]
 pub fn label(args: &mut Args) -> SourceResult<Value> {
     Ok(Value::Label(Label(args.expect("string")?)))
@@ -132,7 +194,12 @@ pub fn label(args: &mut Args) -> SourceResult<Value> {
 
 /// Create a regular expression from a string.
 ///
-/// Tags: create.
+/// # Parameters
+/// - regex: EcoString (positional, required)
+///   The regular expression.
+///
+/// # Tags
+/// - create
 #[func]
 pub fn regex(args: &mut Args) -> SourceResult<Value> {
     let Spanned { v, span } = args.expect::<Spanned<EcoString>>("regular expression")?;
@@ -141,7 +208,18 @@ pub fn regex(args: &mut Args) -> SourceResult<Value> {
 
 /// Create an array consisting of a sequence of numbers.
 ///
-/// Tags: create.
+/// # Parameters
+/// - start: i64 (positional)
+///   The start of the range (inclusive).
+///
+/// - end: i64 (positional, required)
+///   The end of the range (exclusive).
+///
+/// - step: i64 (named)
+///   The distance between the generated numbers.
+///
+/// # Tags
+/// - create
 #[func]
 pub fn range(args: &mut Args) -> SourceResult<Value> {
     let first = args.expect::<i64>("end")?;
diff --git a/library/src/compute/data.rs b/library/src/compute/data.rs
index af545304..5de3eb61 100644
--- a/library/src/compute/data.rs
+++ b/library/src/compute/data.rs
@@ -6,7 +6,12 @@ use crate::prelude::*;
 
 /// Read structured data from a CSV file.
 ///
-/// Tags: data-loading.
+/// # Parameters
+/// - path: EcoString (positional, required)
+///   Path to a CSV file.
+///
+/// # Tags
+/// - data-loading
 #[func]
 pub fn csv(vm: &Vm, args: &mut Args) -> SourceResult<Value> {
     let Spanned { v: path, span } =
@@ -49,7 +54,12 @@ fn format_csv_error(error: csv::Error) -> String {
 
 /// Read structured data from a JSON file.
 ///
-/// Tags: data-loading.
+/// # Parameters
+/// - path: EcoString (positional, required)
+///   Path to a JSON file.
+///
+/// # Tags
+/// - data-loading
 #[func]
 pub fn json(vm: &Vm, args: &mut Args) -> SourceResult<Value> {
     let Spanned { v: path, span } =
@@ -92,7 +102,12 @@ fn format_json_error(error: serde_json::Error) -> String {
 
 /// Read structured data from an XML file.
 ///
-/// Tags: data-loading.
+/// # Parameters
+/// - path: EcoString (positional, required)
+///   Path to an XML file.
+///
+/// # Tags
+/// - data-loading
 #[func]
 pub fn xml(vm: &Vm, args: &mut Args) -> SourceResult<Value> {
     let Spanned { v: path, span } =
diff --git a/library/src/compute/foundations.rs b/library/src/compute/foundations.rs
index 22d26553..cb952d81 100644
--- a/library/src/compute/foundations.rs
+++ b/library/src/compute/foundations.rs
@@ -6,7 +6,12 @@ use typst::syntax::Source;
 
 /// The name of a value's type.
 ///
-/// Tags: foundations.
+/// # Parameters
+/// - value: Value (positional, required)
+///   The value whose type's to determine.
+///
+/// # Tags
+/// - foundations
 #[func]
 pub fn type_(args: &mut Args) -> SourceResult<Value> {
     Ok(args.expect::<Value>("value")?.type_name().into())
@@ -14,7 +19,12 @@ pub fn type_(args: &mut Args) -> SourceResult<Value> {
 
 /// The string representation of a value.
 ///
-/// Tags: foundations.
+/// # Parameters
+/// - value: Value (positional, required)
+///   The value whose string representation to produce.
+///
+/// # Tags
+/// - foundations
 #[func]
 pub fn repr(args: &mut Args) -> SourceResult<Value> {
     Ok(args.expect::<Value>("value")?.repr().into())
@@ -22,7 +32,12 @@ pub fn repr(args: &mut Args) -> SourceResult<Value> {
 
 /// Ensure that a condition is fulfilled.
 ///
-/// Tags: foundations.
+/// # Parameters
+/// - condition: bool (positional, required)
+///   The condition that must be true for the assertion to pass.
+///
+/// # Tags
+/// - foundations
 #[func]
 pub fn assert(args: &mut Args) -> SourceResult<Value> {
     let Spanned { v, span } = args.expect::<Spanned<bool>>("condition")?;
@@ -34,7 +49,12 @@ pub fn assert(args: &mut Args) -> SourceResult<Value> {
 
 /// Evaluate a string as Typst markup.
 ///
-/// Tags: foundations.
+/// # Parameters
+/// - source: String (positional, required)
+///   A string of Typst markup to evaluate.
+///
+/// # Tags
+/// - foundations
 #[func]
 pub fn eval(vm: &Vm, args: &mut Args) -> SourceResult<Value> {
     let Spanned { v: text, span } = args.expect::<Spanned<String>>("source")?;
diff --git a/library/src/compute/utility.rs b/library/src/compute/utility.rs
index 5a6534f4..bdad9618 100644
--- a/library/src/compute/utility.rs
+++ b/library/src/compute/utility.rs
@@ -3,18 +3,30 @@ use std::str::FromStr;
 use crate::prelude::*;
 use crate::text::Case;
 
-/// Create a blind text string.
+/// Create blind text.
 ///
-/// Tags: utility.
+/// # Parameters
+/// - words: usize (positional, required)
+///   The length of the blind text in words.
+///
+/// # Tags
+/// - utility
 #[func]
 pub fn lorem(args: &mut Args) -> SourceResult<Value> {
     let words: usize = args.expect("number of words")?;
     Ok(Value::Str(lipsum::lipsum(words).into()))
 }
 
-/// Apply a numbering pattern to a number.
+/// Apply a numbering pattern to a sequence of numbers.
+///
+/// # Parameters
+/// - pattern: NumberingPattern (positional, required)
+///   A string that defines how the numbering works.
+/// - numbers: NonZeroUsize (positional, variadic)
+///   The numbers to apply the pattern to.
 ///
-/// Tags: utility.
+/// # Tags
+/// - utility
 #[func]
 pub fn numbering(args: &mut Args) -> SourceResult<Value> {
     let pattern = args.expect::<NumberingPattern>("pattern")?;