Annotate return values

library/src/compute/calc.rs

@@ -51,6 +51,8 @@ castable! {
 ///   The sequence of values from which to extract the minimum.
 ///   Must not be empty.
 ///
+/// - returns: any
+///
 /// ## Category
 /// calculate
 #[func]
@@ -72,6 +74,8 @@ pub fn min(args: &mut Args) -> SourceResult<Value> {
 ///   The sequence of values from which to extract the maximum.
 ///   Must not be empty.
 ///
+/// - returns: any
+///
 /// ## Category
 /// calculate
 #[func]
@@ -114,6 +118,8 @@ fn minmax(args: &mut Args, goal: Ordering) -> SourceResult<Value> {
 /// - value: i64 (positional, required)
 ///   The number to check for evenness.
 ///
+/// - returns: boolean
+///
 /// ## Category
 /// calculate
 #[func]
@@ -136,6 +142,8 @@ pub fn even(args: &mut Args) -> SourceResult<Value> {
 /// - value: i64 (positional, required)
 ///   The number to check for oddness.
 ///
+/// - returns: boolean
+///
 /// ## Category
 /// calculate
 #[func]
@@ -159,6 +167,8 @@ pub fn odd(args: &mut Args) -> SourceResult<Value> {
 /// - divisor: ToMod (positional, required)
 ///   The divisor of the modulus.
 ///
+/// - returns: integer or float
+///
 /// ## Category
 /// calculate
 #[func]

library/src/compute/construct.rs

@@ -23,6 +23,8 @@ use crate::prelude::*;
 /// - value: ToInt (positional, required)
 ///   The value that should be converted to an integer.
 ///
+/// - returns: integer
+///
 /// ## Category
 /// construct
 #[func]
@@ -62,6 +64,8 @@ castable! {
 /// - value: ToFloat (positional, required)
 ///   The value that should be converted to a float.
 ///
+/// - returns: float
+///
 /// ## Category
 /// construct
 #[func]
@@ -94,6 +98,8 @@ castable! {
 /// - gray: Component (positional, required)
 ///   The gray component.
 ///
+/// - returns: color
+///
 /// ## Category
 /// construct
 #[func]
@@ -146,6 +152,8 @@ pub fn luma(args: &mut Args) -> SourceResult<Value> {
 /// - alpha: Component (positional)
 ///   The alpha component.
 ///
+/// - returns: color
+///
 /// ## Category
 /// construct
 #[func]
@@ -207,6 +215,8 @@ castable! {
 /// - key: RatioComponent (positional, required)
 ///   The key component.
 ///
+/// - returns: color
+///
 /// ## Category
 /// construct
 #[func]
@@ -249,6 +259,8 @@ castable! {
 /// - value: ToStr (positional, required)
 ///   The value that should be converted to a string.
 ///
+/// - returns: string
+///
 /// ## Category
 /// construct
 #[func]
@@ -291,6 +303,8 @@ castable! {
 /// - name: EcoString (positional, required)
 ///   The name of the label.
 ///
+/// - returns: label
+///
 /// ## Category
 /// construct
 #[func]
@@ -330,6 +344,8 @@ pub fn label(args: &mut Args) -> SourceResult<Value> {
 ///   Typst (e.g. `[\\]`), you need to escape twice. Thus, to match a verbatim
 ///   backslash, you would need to write `{regex("\\\\")}`.
 ///
+/// - returns: regex
+///
 /// ## Category
 /// construct
 #[func]
@@ -364,6 +380,8 @@ pub fn regex(args: &mut Args) -> SourceResult<Value> {
 /// - step: i64 (named)
 ///   The distance between the generated numbers.
 ///
+/// - returns: array
+///
 /// ## Category
 /// construct
 #[func]

library/src/compute/data.rs

@@ -26,11 +26,14 @@ use crate::prelude::*;
 /// ## Parameters
 /// - path: EcoString (positional, required)
 ///   Path to a CSV file.
+///
 /// - delimiter: Delimiter (named)
 ///   The delimiter that separates columns in the CSV file.
 ///   Must be a single ASCII character.
 ///   Defaults to a comma.
 ///
+/// - returns: array
+///
 /// ## Category
 /// data-loading
 #[func]
@@ -140,6 +143,8 @@ fn format_csv_error(error: csv::Error) -> String {
 /// - path: EcoString (positional, required)
 ///   Path to a JSON file.
 ///
+/// - returns: dictionary or array
+///
 /// ## Category
 /// data-loading
 #[func]
@@ -236,6 +241,8 @@ fn format_json_error(error: serde_json::Error) -> String {
 /// - path: EcoString (positional, required)
 ///   Path to an XML file.
 ///
+/// - returns: array
+///
 /// ## Category
 /// data-loading
 #[func]

library/src/compute/foundations.rs

@@ -7,7 +7,7 @@ use typst::syntax::Source;
 /// # Type
 /// Determine a value's type.
 ///
-/// Returns the name of the value's type as a string.
+/// Returns the name of the value's type.
 ///
 /// ## Example
 /// ```
@@ -23,6 +23,8 @@ use typst::syntax::Source;
 /// - value: Value (positional, required)
 ///   The value whose type's to determine.
 ///
+/// - returns: string
+///
 /// ## Category
 /// foundations
 #[func]
@@ -49,6 +51,8 @@ pub fn type_(args: &mut Args) -> SourceResult<Value> {
 /// - value: Value (positional, required)
 ///   The value whose string representation to produce.
 ///
+/// - returns: string
+///
 /// ## Category
 /// foundations
 #[func]
@@ -99,6 +103,8 @@ pub fn assert(args: &mut Args) -> SourceResult<Value> {
 ///
 ///   The markup and code in the string cannot interact with the file system.
 ///
+/// - returns: content
+///
 /// ## Category
 /// foundations
 #[func]

library/src/compute/utility.rs

@@ -24,6 +24,8 @@ use crate::text::Case;
 /// - words: usize (positional, required)
 ///   The length of the blind text in words.
 ///
+/// - returns: string
+///
 /// ## Category
 /// utility
 #[func]
@@ -71,6 +73,8 @@ pub fn lorem(args: &mut Args) -> SourceResult<Value> {
 ///   If more numbers than counting symbols are given, the last counting symbol
 ///   with its prefix is repeated.
 ///
+/// - returns: string
+///
 /// ## Category
 /// utility
 #[func]
@@ -139,11 +143,7 @@ impl FromStr for NumberingPattern {
             };
 
             let prefix = pattern[handled..i].into();
-            let case = if c.is_uppercase() {
-                Case::Upper
-            } else {
-                Case::Lower
-            };
+            let case = if c.is_uppercase() { Case::Upper } else { Case::Lower };
             pieces.push((prefix, kind, case));
             handled = i + 1;
         }

macros/src/func.rs

@@ -17,7 +17,7 @@ pub fn func(item: syn::Item) -> Result<TokenStream> {
 
     let mut docs = docs[first.len()..].to_string();
     let example = example(&mut docs, 2);
-    let params = params(&mut docs)?;
+    let (params, returns) = params(&mut docs)?;
     let syntax = quote_option(section(&mut docs, "Syntax", 2));
     let category = section(&mut docs, "Category", 2).expect("missing category");
     let example = quote_option(example);
@@ -36,6 +36,7 @@ pub fn func(item: syn::Item) -> Result<TokenStream> {
             example: #example,
             syntax: #syntax,
             params: ::std::vec![#(#params),*],
+            returns: ::std::vec![#(#returns),*]
         }
     };
 
@@ -119,10 +120,14 @@ pub fn example(docs: &mut String, level: usize) -> Option<String> {
 }
 
 /// Parse the parameter section.
-fn params(docs: &mut String) -> Result<Vec<TokenStream>> {
-    let Some(section) = section(docs, "Parameters", 2) else { return Ok(vec![]) };
+fn params(docs: &mut String) -> Result<(Vec<TokenStream>, Vec<String>)> {
+    let Some(section) = section(docs, "Parameters", 2) else {
+        return Ok((vec![], vec![]));
+    };
+
     let mut s = Scanner::new(&section);
     let mut infos = vec![];
+    let mut returns = vec![];
 
     while s.eat_if('-') {
         let mut named = false;
@@ -134,6 +139,18 @@ fn params(docs: &mut String) -> Result<Vec<TokenStream>> {
         s.eat_whitespace();
         let name = s.eat_until(':');
         s.expect(": ");
+
+        if name == "returns" {
+            returns = s
+                .eat_until('\n')
+                .split(" or ")
+                .map(str::trim)
+                .map(Into::into)
+                .collect();
+            s.eat_whitespace();
+            continue;
+        }
+
         let ty: syn::Type = syn::parse_str(s.eat_until(char::is_whitespace))?;
         s.eat_whitespace();
         s.expect('(');
@@ -182,5 +199,5 @@ fn params(docs: &mut String) -> Result<Vec<TokenStream>> {
         s.eat_whitespace();
     }
 
-    Ok(infos)
+    Ok((infos, returns))
 }

src/model/func.rs

@@ -217,6 +217,8 @@ pub struct FuncInfo {
     pub syntax: Option<&'static str>,
     /// Details about the function's parameters.
     pub params: Vec<ParamInfo>,
+    /// Valid types for the return value.
+    pub returns: Vec<&'static str>,
 }
 
 impl FuncInfo {