Documentation improvements (#2492)

5 files changed, 40 insertions, 25 deletions

diff --git a/crates/typst-library/src/compute/calc.rs b/crates/typst-library/src/compute/calc.rs
index 8a7c23ea..83bf924e 100644
--- a/crates/typst-library/src/compute/calc.rs
+++ b/crates/typst-library/src/compute/calc.rs
@@ -169,7 +169,7 @@ pub fn exp(
     Ok(result)
 }
 
-/// Extracts the square root of a number.
+/// Calculates the square root of a number.
 ///
 /// ```example
 /// #calc.sqrt(16) \
@@ -486,7 +486,7 @@ fn fact_impl(start: u64, end: u64) -> Option<i64> {
 
 /// Calculates a binomial coefficient.
 ///
-/// Returns the `k`-combination `n`, or the number of ways to choose `k`
+/// Returns the `k`-combination of `n`, or the number of ways to choose `k`
 /// items from a set of `n` without regard to order.
 ///
 /// ```example
@@ -615,7 +615,7 @@ pub fn ceil(
 /// ```example
 /// #assert(calc.trunc(3) == 3)
 /// #assert(calc.trunc(-3.7) == -3)
-/// #assert(calc.trunc(15.9) == 15)
+/// #calc.trunc(15.9)
 /// ```
 #[func(title = "Truncate")]
 pub fn trunc(
diff --git a/crates/typst-library/src/compute/foundations.rs b/crates/typst-library/src/compute/foundations.rs
index b02f9793..fef00269 100644
--- a/crates/typst-library/src/compute/foundations.rs
+++ b/crates/typst-library/src/compute/foundations.rs
@@ -56,6 +56,9 @@ pub fn repr(
 
 /// Fails with an error.
 ///
+/// Arguments are displayed to the user (not rendered in the document) as
+/// strings, converting with `repr` if necessary.
+///
 /// # Example
 /// The code below produces the error `panicked with: "this is wrong"`.
 /// ```typ
@@ -63,7 +66,7 @@ pub fn repr(
 /// ```
 #[func(keywords = ["error"])]
 pub fn panic(
-    /// The values to panic with.
+    /// The values to panic with and display to the user.
     #[variadic]
     values: Vec<Value>,
 ) -> StrResult<Never> {
diff --git a/crates/typst/src/eval/array.rs b/crates/typst/src/eval/array.rs
index 22e38f89..d5757d04 100644
--- a/crates/typst/src/eval/array.rs
+++ b/crates/typst/src/eval/array.rs
@@ -451,15 +451,18 @@ impl Array {
             .collect()
     }
 
-    /// Zips the array with other arrays. If the arrays are of unequal length,
-    /// it will only zip up until the last element of the shortest array and the
-    /// remaining elements will be ignored. The return value is an array where
-    /// each element is yet another array, the size of each of those is the
-    /// number of zipped arrays.
+    /// Zips the array with other arrays.
+    ///
+    /// Returns an array of arrays, where the `i`th inner array contains all the
+    /// `i`th elements from each original array.
+    ///
+    /// If the arrays to be zipped have different lengths, they are zipped up to
+    /// the last element of the shortest array and all remaining elements are
+    /// ignored.
     ///
     /// This function is variadic, meaning that you can zip multiple arrays
-    /// together at once: `{(1, 2, 3).zip((3, 4, 5), (6, 7, 8))}` yields
-    /// `{((1, 3, 6), (2, 4, 7), (3, 5, 8))}`.
+    /// together at once: `{(1, 2).zip(("A", "B"), (10, 20))}` yields
+    /// `{((1, "A", 10), (2, "B", 20))}`.
     #[func]
     pub fn zip(
         self,
diff --git a/crates/typst/src/eval/datetime.rs b/crates/typst/src/eval/datetime.rs
index c76a59bd..a158ad31 100644
--- a/crates/typst/src/eval/datetime.rs
+++ b/crates/typst/src/eval/datetime.rs
@@ -345,7 +345,7 @@ impl Datetime {
         result.map(EcoString::from).map_err(format_time_format_error)
     }
 
-    /// The year if it was specified or `{none}`, otherwise.
+    /// The year if it was specified, or `{none}` for times without a date.
     #[func]
     pub fn year(&self) -> Option<i32> {
         match self {
@@ -355,7 +355,7 @@ impl Datetime {
         }
     }
 
-    /// The month if it was specified or `{none}`, otherwise.
+    /// The month if it was specified, or `{none}` for times without a date.
     #[func]
     pub fn month(&self) -> Option<u8> {
         match self {
@@ -365,7 +365,7 @@ impl Datetime {
         }
     }
 
-    /// The weekday if it was specified or `{none}`, otherwise.
+    /// The weekday (counting Monday as 1) or `{none}` for times without a date.
     #[func]
     pub fn weekday(&self) -> Option<u8> {
         match self {
@@ -375,7 +375,7 @@ impl Datetime {
         }
     }
 
-    /// The day if it was specified or `{none}`, otherwise.
+    /// The day if it was specified, or `{none}` for times without a date.
     #[func]
     pub fn day(&self) -> Option<u8> {
         match self {
@@ -385,7 +385,7 @@ impl Datetime {
         }
     }
 
-    /// The hour if it was specified or `{none}`, otherwise.
+    /// The hour if it was specified, or `{none}` for dates without a time.
     #[func]
     pub fn hour(&self) -> Option<u8> {
         match self {
@@ -395,7 +395,7 @@ impl Datetime {
         }
     }
 
-    /// The minute if it was specified or `{none}`, otherwise.
+    /// The minute if it was specified, or `{none}` for dates without a time.
     #[func]
     pub fn minute(&self) -> Option<u8> {
         match self {
@@ -405,17 +405,17 @@ impl Datetime {
         }
     }
 
-    /// The second if it was specified or `{none}`, otherwise.
+    /// The second if it was specified, or `{none}` for dates without a time.
     #[func]
     pub fn second(&self) -> Option<u8> {
         match self {
-            Datetime::Date(_) => None,
+            Self::Date(_) => None,
             Self::Time(time) => Some(time.second()),
             Self::Datetime(datetime) => Some(datetime.second()),
         }
     }
 
-    /// The ordinal (day of the year), if it exists.
+    /// The ordinal (day of the year), or `{none}` for times without a date.
     #[func]
     pub fn ordinal(&self) -> Option<u16> {
         match self {
diff --git a/crates/typst/src/eval/func.rs b/crates/typst/src/eval/func.rs
index b75e28fa..f24b714b 100644
--- a/crates/typst/src/eval/func.rs
+++ b/crates/typst/src/eval/func.rs
@@ -71,10 +71,19 @@ pub use typst_macros::func;
 /// # Defining functions
 /// You can define your own function with a [let binding]($scripting/#bindings)
 /// that has a parameter list after the binding's name. The parameter list can
-/// contain positional parameters, named parameters with default values and
-/// [argument sinks]($arguments). The right-hand side of the binding can be a
-/// block or any other expression. It defines the function's return value and
-/// can depend on the parameters.
+/// contain mandatory positional parameters, named parameters with default
+/// values and [argument sinks]($arguments).
+///
+/// The right-hand side of a function binding is the function body, which can be
+/// a block or any other expression. It defines the function's return value and
+/// can depend on the parameters. If the function body is a [code
+/// block]($scripting/#blocks), the return value is the result of joining the
+/// values of each expression in the block.
+///
+/// Within a function body, the `return` keyword can be used to exit early and
+/// optionally specify a return value. If no explicit return value is given, the
+/// body evaluates to the result of joining all expressions preceding the
+/// `return`.
 ///
 /// ```example
 /// #let alert(body, fill: red) = {
@@ -110,7 +119,7 @@ pub use typst_macros::func;
 /// once?
 /// ```
 ///
-/// # Notable fact
+/// # Note on function purity
 /// In Typst, all functions are _pure._ This means that for the same
 /// arguments, they always return the same result. They cannot "remember" things to
 /// produce another value when they are called a second time.