Document foundations

library/src/compute/calc.rs

@@ -43,7 +43,7 @@ castable! {
 /// ## Example
 /// ```
 /// #min(1, -3, -5, 20, 3, 6) \
-/// #min("Typst", "in", "beta")
+/// #min("typst", "in", "beta")
 /// ```
 ///
 /// ## Parameters
@@ -64,7 +64,7 @@ pub fn min(args: &mut Args) -> SourceResult<Value> {
 /// ## Example
 /// ```
 /// #max(1, -3, -5, 20, 3, 6) \
-/// #max("Typst", "in", "beta")
+/// #max("typst", "in", "beta")
 /// ```
 ///
 /// ## Parameters

library/src/compute/foundations.rs

@@ -5,7 +5,19 @@ use typst::model;
 use typst::syntax::Source;
 
 /// # Type
-/// The name of a value's type.
+/// Determine a value's type.
+///
+/// Returns the name of the value's type as a string.
+///
+/// ## Example
+/// ```
+/// #type(12) \
+/// #type(14.7) \
+/// #type("hello") \
+/// #type(none) \
+/// #type([Hi]) \
+/// #type(x => x + 1)
+/// ```
 ///
 /// ## Parameters
 /// - value: Value (positional, required)
@@ -21,6 +33,17 @@ pub fn type_(args: &mut Args) -> SourceResult<Value> {
 /// # Representation
 /// The string representation of a value.
 ///
+/// When inserted into content, most values are displayed as this representation
+/// in monospace with syntax-highlighting. The exceptions are `{none}`,
+/// integers, floats, strings, content, and functions.
+///
+/// ## Example
+/// ```
+/// { none } vs #repr(none) \
+/// { "hello" } vs #repr("hello") \
+/// { (1, 2) } vs #repr((1, 2))
+/// ```
+///
 /// ## Parameters
 /// - value: Value (positional, required)
 ///   The value whose string representation to produce.
@@ -35,6 +58,14 @@ pub fn repr(args: &mut Args) -> SourceResult<Value> {
 /// # Assert
 /// Ensure that a condition is fulfilled.
 ///
+/// Fails with an error if the condition is not fulfilled. Does not
+/// produce any output in the document.
+///
+/// ## Example
+/// ```
+/// #assert(1 < 2)
+/// ```
+///
 /// ## Parameters
 /// - condition: bool (positional, required)
 ///   The condition that must be true for the assertion to pass.
@@ -53,10 +84,20 @@ pub fn assert(args: &mut Args) -> SourceResult<Value> {
 /// # Evaluate
 /// Evaluate a string as Typst markup.
 ///
+/// You shouldn't typically need this function, but it is there if you do.
+///
+/// ## Example
+/// ```
+/// #let markup = "= Heading\n _Emphasis_"
+/// #eval(markup)
+/// ```
+///
 /// ## Parameters
 /// - source: String (positional, required)
 ///   A string of Typst markup to evaluate.
 ///
+///   The markup and code in the string cannot interact with the file system.
+///
 /// ## Category
 /// foundations
 #[func]