From a936188e46d28ea3926e2c7c341bf129f43c62a3 Mon Sep 17 00:00:00 2001 From: codex Date: Sun, 28 Jun 2026 00:06:30 -0500 Subject: [PATCH] Add XMLDoc documentation to functions --- src/StandardLibrary/Functions/Lerp.cs | 24 +++++ src/StandardLibrary/Functions/Log.cs | 23 +++++ src/StandardLibrary/Functions/Map.cs | 28 ++++++ src/StandardLibrary/Functions/Natural Log.cs | 23 +++++ src/StandardLibrary/Functions/Normalize.cs | 25 +++++ .../Functions/NumberTheory/Fibonacci.cs | 26 ++++- .../Functions/NumberTheory/Identity.cs | 98 +++++++++++++++++++ src/StandardLibrary/Functions/Power.cs | 23 +++++ src/StandardLibrary/Functions/SmoothStep.cs | 24 +++++ src/StandardLibrary/Functions/SquareRoot.cs | 23 +++++ 10 files changed, 316 insertions(+), 1 deletion(-) diff --git a/src/StandardLibrary/Functions/Lerp.cs b/src/StandardLibrary/Functions/Lerp.cs index 0993d86..44ce930 100644 --- a/src/StandardLibrary/Functions/Lerp.cs +++ b/src/StandardLibrary/Functions/Lerp.cs @@ -4,8 +4,19 @@ using System.Text; namespace CSMic.StandardLibrary.Functions { + /// + /// Represents the standard-library lerp function. + /// + /// + /// The lerp function evaluates two numeric endpoints and an interpolation amount, then returns the value + /// at that position between the endpoints. + /// public class Lerp: FunctionBase, ICodedFunction { + /// + /// Gets the expression-language name used to invoke this function. + /// + /// lerp. public string Name { get @@ -14,6 +25,10 @@ namespace CSMic.StandardLibrary.Functions } } + /// + /// Gets the argument signature expected by the lerp function. + /// + /// Three numeric arguments named start, end, and ammount. public override IEnumerable ExpectedArguments { get @@ -24,6 +39,15 @@ namespace CSMic.StandardLibrary.Functions } } + /// + /// Executes the lerp function. + /// + /// + /// The evaluated arguments supplied to the function. Exactly three numeric arguments are expected. + /// + /// + /// A numeric containing the linearly interpolated value. + /// public FunctionValue Execute(params FunctionArgument[] args) { return base.Execute(args, (_args) => diff --git a/src/StandardLibrary/Functions/Log.cs b/src/StandardLibrary/Functions/Log.cs index efc2e8a..2df19b0 100644 --- a/src/StandardLibrary/Functions/Log.cs +++ b/src/StandardLibrary/Functions/Log.cs @@ -4,8 +4,18 @@ using System.Text; namespace CSMic.StandardLibrary.Functions { + /// + /// Represents the standard-library log function. + /// + /// + /// The log function evaluates a numeric expression and returns its logarithm in the supplied base. + /// public class Log: FunctionBase, ICodedFunction { + /// + /// Gets the expression-language name used to invoke this function. + /// + /// log. public string Name { get @@ -14,6 +24,10 @@ namespace CSMic.StandardLibrary.Functions } } + /// + /// Gets the argument signature expected by the log function. + /// + /// Two numeric arguments named value and base. public override IEnumerable ExpectedArguments { get @@ -23,6 +37,15 @@ namespace CSMic.StandardLibrary.Functions } } + /// + /// Executes the log function. + /// + /// + /// The evaluated arguments supplied to the function. Exactly two numeric arguments are expected. + /// + /// + /// A numeric containing the logarithm of the input value in the supplied base. + /// public FunctionValue Execute(params FunctionArgument[] args) { return base.Execute(args, (_args) => diff --git a/src/StandardLibrary/Functions/Map.cs b/src/StandardLibrary/Functions/Map.cs index 665b79f..23ecccd 100644 --- a/src/StandardLibrary/Functions/Map.cs +++ b/src/StandardLibrary/Functions/Map.cs @@ -4,8 +4,19 @@ using System.Text; namespace CSMic.StandardLibrary.Functions { + /// + /// Represents the standard-library map function. + /// + /// + /// The map function evaluates a numeric value from one range and returns the corresponding value in a + /// second range. + /// public class Map: FunctionBase, ICodedFunction { + /// + /// Gets the expression-language name used to invoke this function. + /// + /// map. public string Name { get @@ -14,6 +25,13 @@ namespace CSMic.StandardLibrary.Functions } } + /// + /// Gets the argument signature expected by the map function. + /// + /// + /// Five numeric arguments named value, oldMinimum, oldMaximum, + /// newMinimum, and newMaximum. + /// public override IEnumerable ExpectedArguments { get @@ -26,6 +44,16 @@ namespace CSMic.StandardLibrary.Functions } } + /// + /// Executes the map function. + /// + /// + /// The evaluated arguments supplied to the function. Exactly five numeric arguments are expected. + /// + /// + /// A numeric containing the mapped value, or 0 when the source range has + /// equal minimum and maximum bounds. + /// public FunctionValue Execute(params FunctionArgument[] args) { return base.Execute(args, (_args) => diff --git a/src/StandardLibrary/Functions/Natural Log.cs b/src/StandardLibrary/Functions/Natural Log.cs index 94252af..5cd45c1 100644 --- a/src/StandardLibrary/Functions/Natural Log.cs +++ b/src/StandardLibrary/Functions/Natural Log.cs @@ -4,8 +4,18 @@ using System.Text; namespace CSMic.StandardLibrary.Functions { + /// + /// Represents the standard-library ln function. + /// + /// + /// The ln function evaluates a numeric expression and returns its natural logarithm. + /// public class Natural_Log: FunctionBase, ICodedFunction { + /// + /// Gets the expression-language name used to invoke this function. + /// + /// ln. public string Name { get @@ -14,6 +24,10 @@ namespace CSMic.StandardLibrary.Functions } } + /// + /// Gets the argument signature expected by the ln function. + /// + /// A single numeric argument named value. public override IEnumerable ExpectedArguments { get @@ -22,6 +36,15 @@ namespace CSMic.StandardLibrary.Functions } } + /// + /// Executes the ln function. + /// + /// + /// The evaluated arguments supplied to the function. Exactly one numeric argument is expected. + /// + /// + /// A numeric containing the natural logarithm of the input. + /// public FunctionValue Execute(params FunctionArgument[] args) { return base.Execute(args, (_args) => diff --git a/src/StandardLibrary/Functions/Normalize.cs b/src/StandardLibrary/Functions/Normalize.cs index 3a2fc74..2a461d1 100644 --- a/src/StandardLibrary/Functions/Normalize.cs +++ b/src/StandardLibrary/Functions/Normalize.cs @@ -4,8 +4,19 @@ using System.Text; namespace CSMic.StandardLibrary.Functions { + /// + /// Represents the standard-library normalize function. + /// + /// + /// The normalize function evaluates a numeric value and returns its position in the supplied range as a + /// zero-based ratio. + /// public class Normalize : FunctionBase, ICodedFunction { + /// + /// Gets the expression-language name used to invoke this function. + /// + /// normalize. public string Name { get @@ -14,6 +25,10 @@ namespace CSMic.StandardLibrary.Functions } } + /// + /// Gets the argument signature expected by the normalize function. + /// + /// Three numeric arguments named value, minimum, and maximum. public override IEnumerable ExpectedArguments { get @@ -24,6 +39,16 @@ namespace CSMic.StandardLibrary.Functions } } + /// + /// Executes the normalize function. + /// + /// + /// The evaluated arguments supplied to the function. Exactly three numeric arguments are expected. + /// + /// + /// A numeric containing the normalized ratio, or 0 when the minimum and + /// maximum bounds are equal. + /// public FunctionValue Execute(params FunctionArgument[] args) { return base.Execute(args, (_args) => diff --git a/src/StandardLibrary/Functions/NumberTheory/Fibonacci.cs b/src/StandardLibrary/Functions/NumberTheory/Fibonacci.cs index 932aa41..f330105 100644 --- a/src/StandardLibrary/Functions/NumberTheory/Fibonacci.cs +++ b/src/StandardLibrary/Functions/NumberTheory/Fibonacci.cs @@ -4,7 +4,13 @@ using System.Text; namespace CSMic.StandardLibrary.Functions.NumberTheory { - /// + /// + /// Represents the standard-library fib function. + /// + /// + /// The fib function evaluates a numeric index and returns the precomputed Fibonacci number at that index. + /// Indexes outside the supported range return 0. + /// public class Fibonacci : FunctionBase, ICodedFunction { @@ -40,6 +46,10 @@ namespace CSMic.StandardLibrary.Functions.NumberTheory 11825896447871834976429068427m, 19134702400093278081449423917m, 30960598847965113057878492344m, 50095301248058391139327916261m]; + /// + /// Gets the expression-language name used to invoke this function. + /// + /// fib. public string Name { get @@ -48,6 +58,10 @@ namespace CSMic.StandardLibrary.Functions.NumberTheory } } + /// + /// Gets the argument signature expected by the fib function. + /// + /// A single numeric argument named index. public override IEnumerable ExpectedArguments { get @@ -56,6 +70,16 @@ namespace CSMic.StandardLibrary.Functions.NumberTheory } } + /// + /// Executes the fib function. + /// + /// + /// The evaluated arguments supplied to the function. Exactly one numeric argument is expected. + /// + /// + /// A numeric containing the Fibonacci number at the supplied index, or 0 + /// when the index is outside the supported range. + /// public FunctionValue Execute(params FunctionArgument[] args) { return base.Execute(args, (_args) => diff --git a/src/StandardLibrary/Functions/NumberTheory/Identity.cs b/src/StandardLibrary/Functions/NumberTheory/Identity.cs index 9f7b410..a743224 100644 --- a/src/StandardLibrary/Functions/NumberTheory/Identity.cs +++ b/src/StandardLibrary/Functions/NumberTheory/Identity.cs @@ -5,8 +5,19 @@ using System.Text; namespace CSMic.StandardLibrary.Functions.NumberTheory { + /// + /// Represents the standard-library iseven function. + /// + /// + /// The iseven function evaluates a numeric expression and returns 1 when the value is even; + /// otherwise, it returns 0. + /// public class IsEven : FunctionBase, ICodedFunction { + /// + /// Gets the expression-language name used to invoke this function. + /// + /// iseven. public string Name { get @@ -15,6 +26,10 @@ namespace CSMic.StandardLibrary.Functions.NumberTheory } } + /// + /// Gets the argument signature expected by the iseven function. + /// + /// A single numeric argument named value. public override IEnumerable ExpectedArguments { get @@ -23,6 +38,15 @@ namespace CSMic.StandardLibrary.Functions.NumberTheory } } + /// + /// Executes the iseven function. + /// + /// + /// The evaluated arguments supplied to the function. Exactly one numeric argument is expected. + /// + /// + /// A numeric containing 1 when the input value is even; otherwise 0. + /// public FunctionValue Execute(params FunctionArgument[] args) { return base.Execute(args, (_args) => @@ -41,8 +65,19 @@ namespace CSMic.StandardLibrary.Functions.NumberTheory } } + /// + /// Represents the standard-library isodd function. + /// + /// + /// The isodd function evaluates a numeric expression and returns 1 when the value is odd; + /// otherwise, it returns 0. + /// public class IsOdd : FunctionBase, ICodedFunction { + /// + /// Gets the expression-language name used to invoke this function. + /// + /// isodd. public string Name { get @@ -51,6 +86,10 @@ namespace CSMic.StandardLibrary.Functions.NumberTheory } } + /// + /// Gets the argument signature expected by the isodd function. + /// + /// A single numeric argument named value. public override IEnumerable ExpectedArguments { get @@ -59,6 +98,15 @@ namespace CSMic.StandardLibrary.Functions.NumberTheory } } + /// + /// Executes the isodd function. + /// + /// + /// The evaluated arguments supplied to the function. Exactly one numeric argument is expected. + /// + /// + /// A numeric containing 1 when the input value is odd; otherwise 0. + /// public FunctionValue Execute(params FunctionArgument[] args) { return base.Execute(args, (_args) => @@ -72,8 +120,19 @@ namespace CSMic.StandardLibrary.Functions.NumberTheory } } + /// + /// Represents the standard-library isint function. + /// + /// + /// The isint function evaluates a numeric expression and returns 1 when the value has no fractional + /// component; otherwise, it returns 0. + /// public class IsInt : FunctionBase, ICodedFunction { + /// + /// Gets the expression-language name used to invoke this function. + /// + /// isint. public string Name { get @@ -82,6 +141,10 @@ namespace CSMic.StandardLibrary.Functions.NumberTheory } } + /// + /// Gets the argument signature expected by the isint function. + /// + /// A single numeric argument named value. public override IEnumerable ExpectedArguments { get @@ -90,6 +153,16 @@ namespace CSMic.StandardLibrary.Functions.NumberTheory } } + /// + /// Executes the isint function. + /// + /// + /// The evaluated arguments supplied to the function. Exactly one numeric argument is expected. + /// + /// + /// A numeric containing 1 when the input value is an integer; otherwise + /// 0. + /// public FunctionValue Execute(params FunctionArgument[] args) { return base.Execute(args, (_args) => @@ -108,6 +181,13 @@ namespace CSMic.StandardLibrary.Functions.NumberTheory } } + /// + /// Represents the standard-library isprime function. + /// + /// + /// The isprime function evaluates a numeric expression and returns 1 when the value is a prime + /// integer; otherwise, it returns 0. + /// public class IsPrime : FunctionBase, ICodedFunction { private const int MaxPrimeCacheSize = 4096; @@ -135,6 +215,10 @@ namespace CSMic.StandardLibrary.Functions.NumberTheory false, false, false, true, false, false, false, false, false, true, false, false, false, false, false, false, false, true, false, false]; + /// + /// Gets the expression-language name used to invoke this function. + /// + /// isprime. public string Name { get @@ -143,6 +227,10 @@ namespace CSMic.StandardLibrary.Functions.NumberTheory } } + /// + /// Gets the argument signature expected by the isprime function. + /// + /// A single numeric argument named value. public override IEnumerable ExpectedArguments { get @@ -151,6 +239,16 @@ namespace CSMic.StandardLibrary.Functions.NumberTheory } } + /// + /// Executes the isprime function. + /// + /// + /// The evaluated arguments supplied to the function. Exactly one numeric argument is expected. + /// + /// + /// A numeric containing 1 when the input value is prime; otherwise + /// 0. + /// public FunctionValue Execute(params FunctionArgument[] args) { return base.Execute(args, (_args) => diff --git a/src/StandardLibrary/Functions/Power.cs b/src/StandardLibrary/Functions/Power.cs index a6dcd37..ffab27d 100644 --- a/src/StandardLibrary/Functions/Power.cs +++ b/src/StandardLibrary/Functions/Power.cs @@ -4,8 +4,18 @@ using System.Text; namespace CSMic.StandardLibrary.Functions { + /// + /// Represents the standard-library pow function. + /// + /// + /// The pow function evaluates a numeric base and exponent, then returns the base raised to that exponent. + /// public class Power : FunctionBase, ICodedFunction { + /// + /// Gets the expression-language name used to invoke this function. + /// + /// pow. public string Name { get @@ -14,6 +24,10 @@ namespace CSMic.StandardLibrary.Functions } } + /// + /// Gets the argument signature expected by the pow function. + /// + /// Two numeric arguments named base and exponent. public override IEnumerable ExpectedArguments { get @@ -23,6 +37,15 @@ namespace CSMic.StandardLibrary.Functions } } + /// + /// Executes the pow function. + /// + /// + /// The evaluated arguments supplied to the function. Exactly two numeric arguments are expected. + /// + /// + /// A numeric containing the base raised to the supplied exponent. + /// public FunctionValue Execute(params FunctionArgument[] args) { return base.Execute(args, (_args) => diff --git a/src/StandardLibrary/Functions/SmoothStep.cs b/src/StandardLibrary/Functions/SmoothStep.cs index b375d63..fe9fd40 100644 --- a/src/StandardLibrary/Functions/SmoothStep.cs +++ b/src/StandardLibrary/Functions/SmoothStep.cs @@ -4,8 +4,19 @@ using System.Text; namespace CSMic.StandardLibrary.Functions { + /// + /// Represents the standard-library lerp smooth-step function. + /// + /// + /// This function evaluates a value between two edges, clamps it to the range from 0 through 1, and + /// applies the smooth-step polynomial x * x * (3 - 2 * x). + /// public class SmoothStep : FunctionBase, ICodedFunction { + /// + /// Gets the expression-language name used to invoke this function. + /// + /// lerp. public string Name { get @@ -14,6 +25,10 @@ namespace CSMic.StandardLibrary.Functions } } + /// + /// Gets the argument signature expected by the lerp smooth-step function. + /// + /// Three numeric arguments named startEdge, endEdge, and value. public override IEnumerable ExpectedArguments { get @@ -24,6 +39,15 @@ namespace CSMic.StandardLibrary.Functions } } + /// + /// Executes the lerp smooth-step function. + /// + /// + /// The evaluated arguments supplied to the function. Exactly three numeric arguments are expected. + /// + /// + /// A numeric containing the smoothed interpolation ratio. + /// public FunctionValue Execute(params FunctionArgument[] args) { return base.Execute(args, (_args) => diff --git a/src/StandardLibrary/Functions/SquareRoot.cs b/src/StandardLibrary/Functions/SquareRoot.cs index d6e25fd..f101f5b 100644 --- a/src/StandardLibrary/Functions/SquareRoot.cs +++ b/src/StandardLibrary/Functions/SquareRoot.cs @@ -4,8 +4,18 @@ using System.Text; namespace CSMic.StandardLibrary.Functions { + /// + /// Represents the standard-library sqrt function. + /// + /// + /// The sqrt function evaluates a numeric expression and returns its square root. + /// public class SquareRoot: FunctionBase, ICodedFunction { + /// + /// Gets the expression-language name used to invoke this function. + /// + /// sqrt. public string Name { get @@ -14,6 +24,10 @@ namespace CSMic.StandardLibrary.Functions } } + /// + /// Gets the argument signature expected by the sqrt function. + /// + /// A single numeric argument named value. public override IEnumerable ExpectedArguments { get @@ -22,6 +36,15 @@ namespace CSMic.StandardLibrary.Functions } } + /// + /// Executes the sqrt function. + /// + /// + /// The evaluated arguments supplied to the function. Exactly one numeric argument is expected. + /// + /// + /// A numeric containing the square root of the input. + /// public FunctionValue Execute(params FunctionArgument[] args) { return base.Execute(args, (_args) =>