diff --git a/src/StandardLibrary/functions/FunctionBase.cs b/src/StandardLibrary/functions/FunctionBase.cs index 5708d7a..fb5a65c 100644 --- a/src/StandardLibrary/functions/FunctionBase.cs +++ b/src/StandardLibrary/functions/FunctionBase.cs @@ -2,27 +2,39 @@ namespace CSMic.StandardLibrary.Functions { - /// A base class that handles base function handling. + /// + /// Provides shared argument validation and execution handling for standard-library functions. + /// + /// + /// Derive from this class when implementing an that follows the + /// standard-library function contract. + /// public abstract class FunctionBase { - /// Gets the expected arguments. - /// The expected arguments. + /// Gets the argument signature expected by the function. + /// The ordered collection of arguments required by the function. public virtual IEnumerable ExpectedArguments { get; } - /// Gets the return value. - /// The return value. + /// Gets the return type produced by the function. + /// + /// The expected return value type. The default is . + /// public virtual FunctionValue ReturnValue { get - { return FunctionValue.NUMBER; } } - /// Checks the provided arguments to ensure the function contract is honored. - /// A variable-length parameters list containing arguments. - /// True if it succeeds, false if it fails. + /// + /// Determines whether the supplied arguments satisfy the function's expected signature. + /// + /// The evaluated arguments supplied to the function. + /// + /// if the supplied arguments match the expected count and value types; + /// otherwise, . + /// public bool ArgumentCheck(params FunctionArgument[] args) { // Top level sanity checks. @@ -57,10 +69,14 @@ namespace CSMic.StandardLibrary.Functions return true; } - /// Executes a standard library function. - /// A variable-length parameters list containing arguments. - /// The functions action body. - /// A . + /// Validates and executes a standard-library function body. + /// The evaluated arguments supplied to the function. + /// The function implementation to execute after argument validation + /// succeeds. + /// + /// The result returned by , or if + /// validation fails or execution throws an exception. + /// public FunctionValue Execute(FunctionArgument[] args, Func action) { if (!ArgumentCheck(args)) diff --git a/src/StandardLibrary/functions/Sign.cs b/src/StandardLibrary/functions/Sign.cs index 4ad01d9..3dcac70 100644 --- a/src/StandardLibrary/functions/Sign.cs +++ b/src/StandardLibrary/functions/Sign.cs @@ -3,7 +3,16 @@ namespace CSMic.StandardLibrary.Functions { - /// A function that returns 1 if the expression is positive and -1 if it is negative. + /// + /// Represents the standard-library sign function. + /// + /// + /// The sign function evaluates a numeric expression and returns: + /// + /// 1 when the value is greater than or equal to zero. + /// -1 when the value is less than zero. + /// + /// public class Sign : FunctionBase, ICodedFunction { /// (Immutable) The return value representing "positive". @@ -11,8 +20,10 @@ namespace CSMic.StandardLibrary.Functions /// (Immutable) The return value representing "negative". private const decimal NEGATIVE = -1; - /// Gets the name of the function. - /// sign. + /// + /// Gets the expression-language name used to invoke this function. + /// [ + /// sign. public string Name { get @@ -21,8 +32,12 @@ namespace CSMic.StandardLibrary.Functions } } - /// Gets the expected arguments. - /// The expected arguments. + /// + /// Gets the argument signature expected by the sign function. + /// + /// + /// A single numeric argument named value. + /// public override IEnumerable ExpectedArguments { get @@ -31,9 +46,16 @@ namespace CSMic.StandardLibrary.Functions } } - /// Executes the function with the given arguments. - /// A variable-length parameters list containing arguments. - /// A representing the result of the function execution. + /// + /// Executes the sign function. + /// + /// + /// The evaluated arguments supplied to the function. Exactly one numeric argument is expected. + /// + /// + /// A numeric containing 1 when the input value is greater than + /// or equal to zero; otherwise -1. + /// public FunctionValue Execute(params FunctionArgument[] args) { return base.Execute(args, (_args) =>