[orx-expression-evaluator-typed] Add generated and verified documenta…

…tion

orx-expression-evaluator-typed/src/commonMain/kotlin/typed/CompiledFunctions.kt

@@ -2,8 +2,17 @@ package org.openrndr.extra.expressions.typed
 
 import org.antlr.v4.kotlinruntime.tree.ParseTreeWalker
 
+
 /**
- * Compile a function
+ * Compiles a string expression into a single-parameter function capable of evaluating the expression.
+ *
+ * @param T0 The type of the single parameter that will be passed to the compiled function.
+ * @param R The return type of the compiled function.
+ * @param expression The string representation of the expression to be compiled.
+ * @param parameter0 The name of the required parameter in the expression.
+ * @param constants A lambda function to resolve constants in the expression by their names. Defaults to a function returning null for all names.
+ * @param functions A set of function extensions that can be used within the expression. Defaults to an empty set.
+ * @return A single-parameter function that takes an argument of type [T0] and evaluates the expression to return a result of type [R].
  */
 fun <T0, R> compileFunction1(
     expression: String,
@@ -38,6 +47,21 @@ fun <T0, R> compileFunction1(
     }
 }
 
+/**
+ * Tries to compile a given string expression into a single-parameter function. Returns the compiled function if successful,
+ * or `null` if an error occurs during compilation. Errors are handled using the provided [onError] callback.
+ *
+ * @param T0 The type of the single parameter that will be passed to the compiled function.
+ * @param R The return type of the compiled function.
+ * @param expression The string representation of the expression to be compiled.
+ * @param parameter0 The name of the required parameter in the expression.
+ * @param constants A lambda function to resolve constants in the expression by their names. Defaults to a function returning null for all names.
+ * @param functions A set of function extensions that can be used within the expression. Defaults to an empty set.
+ * @param onError A callback function that will be invoked when an error occurs during compilation.
+ *                The error is passed to this function.
+ * @return A single-parameter function that takes an argument of type [T0] and evaluates the expression to return a result of type [R],
+ *         or `null` if the compilation fails.
+ */
 fun <T0, R> compileFunction1OrNull(
     expression: String,
     parameter0: String,
@@ -53,8 +77,25 @@ fun <T0, R> compileFunction1OrNull(
     }
 }
 
-//
-
+/**
+ * Compiles a string expression into a lambda function with two parameters.
+ *
+ * This function takes an expression as a string, as well as two parameter names,
+ * and returns a lambda that evaluates the expression with the provided parameter values.
+ * Optionally, a map of constants and custom functions can be provided for use in the expression.
+ *
+ * @param T0 The type of the first parameter.
+ * @param T1 The type of the second parameter.
+ * @param R The return type of the resulting lambda function.
+ * @param expression The string expression to compile.
+ * @param parameter0 The name of the first parameter in the expression.
+ * @param parameter1 The name of the second parameter in the expression.
+ * @param constants A lambda function that provides constant values by variable name. Defaults to returning null for all names.
+ * @param functions The custom functions available in the context of the expression. Defaults to an empty set of functions.
+ * @return A lambda function that takes two parameters of types T0 and T1 and returns a result of type R,
+ *         based on the compiled expression.
+ * @throws IllegalArgumentException if either parameter name exists within the constants map.
+ */
 fun <T0, T1, R> compileFunction2(
     expression: String,
     parameter0: String,
@@ -93,6 +134,26 @@ fun <T0, T1, R> compileFunction2(
     }
 }
 
+/**
+ * Attempts to compile a string expression into a lambda function with two parameters,
+ * returning null if an error occurs during compilation.
+ *
+ * This function is a safe wrapper around `compileFunction2`, catching any exceptions
+ * that may be thrown during the compilation process. If an error occurs, the provided
+ * `onError` callback is invoked with the exception, and the function returns null.
+ *
+ * @param T0 The type of the first parameter.
+ * @param T1 The type of the second parameter.
+ * @param R The return type of the resulting lambda function.
+ * @param expression The string expression to compile.
+ * @param parameter0 The name of the first parameter in the expression.
+ * @param parameter1 The name of the second parameter in the expression.
+ * @param constants A lambda function that provides constant values for variables by name. Defaults to returning null for all names.
+ * @param functions The custom functions available in the context of the expression. Defaults to an empty set of functions.
+ * @param onError A callback invoked with the exception if an error occurs during compilation. Defaults to an empty function.
+ * @return A lambda function that takes two parameters of types T0 and T1 and returns a result of type R if the compilation is successful.
+ *         Returns null if an error occurs during compilation.
+ */
 fun <T0, T1, R> compileFunction2OrNull(
     expression: String,
     parameter0: String,
@@ -109,8 +170,23 @@ fun <T0, T1, R> compileFunction2OrNull(
     }
 }
 
-//
-
+/**
+ * Compiles a 3-parameter function from a given string expression, allowing dynamic evaluation with specified parameters, constants, and external function extensions.
+ *
+ * @param T0 The type of the first parameter.
+ * @param T1 The type of the second parameter.
+ * @param T2 The type of the third parameter.
+ * @param R The return type of the compiled function.
+ * @param expression The string representation of the expression to be compiled.
+ * @param parameter0 The name of the first parameter referenced in the expression.
+ * @param parameter1 The name of the second parameter referenced in the expression.
+ * @param parameter2 The name of the third parameter referenced in the expression.
+ * @param constants A lambda function providing constant values for variable names used in the expression. Defaults to a function returning null.
+ * @param functions An optional container of external functions that can be called within the expression. Defaults to an empty set of functions.
+ * @return A lambda function that takes three parameters of types T0, T1, and T2, and returns a result of type R after evaluating the compiled expression.
+ * @throws IllegalArgumentException If any of the parameter names are found in the constants map.
+ * @throws ExpressionException If there is a syntax error in the provided expression.
+ */
 fun <T0, T1, T2, R> compileFunction3(
     expression: String,
     parameter0: String,
@@ -157,6 +233,23 @@ fun <T0, T1, T2, R> compileFunction3(
     }
 }
 
+/**
+ * Compiles a 3-parameter function from a given string expression, returning null if an error occurs during compilation.
+ *
+ * @param T0 The type of the first parameter.
+ * @param T1 The type of the second parameter.
+ * @param T2 The type of the third parameter.
+ * @param R The return type of the compiled function.
+ * @param expression The string representation of the expression to be compiled.
+ * @param parameter0 The name of the first parameter referenced in the expression.
+ * @param parameter1 The name of the second parameter referenced in the expression.
+ * @param parameter2 The name of the third parameter referenced in the expression.
+ * @param constants A lambda function providing constant values for variable names used in the expression. Defaults to a function returning null.
+ * @param functions An optional container of external functions that can be called within the expression. Defaults to an empty set of functions.
+ * @param onError A lambda function that will be invoked with the exception if an error occurs during compilation. Defaults to an empty function.
+ * @return A lambda function that takes three parameters of types T0, T1, and T2, and returns a result of type R after evaluating the compiled expression, or null if an error occurs
+ * .
+ */
 fun <T0, T1, T2, R> compileFunction3OrNull(
     expression: String,
     parameter0: String,

orx-expression-evaluator-typed/src/commonMain/kotlin/typed/TypedExpressions.kt

@@ -63,6 +63,19 @@ enum class IDType {
     FUNCTION_ARGUMENT
 }
 
+/**
+ * A base class for handling typed expressions in a custom language parser.
+ * This class provides an extensive set of overrides for various parser rules
+ * to allow custom implementation when these rules are triggered during parsing.
+ *
+ * @property functions Represents a mapping of functions categorized by their arity.
+ * @property constants Tracks constants identified during parsing.
+ * @property state Maintains the current state of the listener, preserving contextual information.
+ *
+ * Methods primarily handle entering and exiting parser rules for expressions, statements, and
+ * function calls, offering hooks to extend or modify behavior for each parsing scenario. Additionally,
+ * utility methods are provided to handle and propagate errors during parsing.
+ */
 abstract class TypedExpressionListenerBase(
     val functions: TypedFunctionExtensions = TypedFunctionExtensions.EMPTY,
     val constants: (String) -> Any? = { null }
@@ -940,6 +953,21 @@ expect class TypedExpressionListener(
 
 class ExpressionException(message: String) : RuntimeException(message)
 
+/**
+ * Evaluates a typed expression based on the provided string input, constants,
+ * and function definitions.
+ *
+ * @param expression The string representation of the expression to evaluate.
+ * @param constants A lambda function providing constant values for specific
+ * variables. Returns null if a constant is not found. Defaults to a function
+ * returning null for any input.
+ * @param functions A `TypedFunctionExtensions` instance encapsulating function
+ * definitions for 0 to 5 arguments. Defaults to an empty set of functions.
+ * @return The result of the evaluated expression as an `Any?` type.
+ *         Returns null if the evaluation produces no result.
+ * @throws ExpressionException If a syntax error occurs in the input expression
+ * or during expression evaluation.
+ */
 fun evaluateTypedExpression(
     expression: String,
     constants: (String) -> Any? = { null },