wagesj45/cs-mic
1
0
Fork 0
Code Issues Pull requests Releases Packages 2 Wiki Activity Actions

Polishing XMLDoc conventions

Browse source
This commit is contained in:
Jordan Wages 2026-06-24 13:54:15 -05:00
commit b911ccfbfe
2 changed files with 59 additions and 21 deletions
Download patch file Download diff file Expand all files Collapse all files

42
src/StandardLibrary/functions/FunctionBase.cs
View file

@ -2,27 +2,39 @@
namespace CSMic.StandardLibrary.Functions
{
/// <summary> A base class that handles base function handling. </summary>
/// <summary>
/// Provides shared argument validation and execution handling for standard-library functions.
/// </summary>
/// <remarks>
/// Derive from this class when implementing an <see cref="ICodedFunction"/> that follows the
/// standard-library function contract.
/// </remarks>
public abstract class FunctionBase
{
/// <summary> Gets the expected arguments. </summary>
/// <value> The expected arguments. </value>
/// <summary> Gets the argument signature expected by the function. </summary>
/// <value> The ordered collection of arguments required by the function. </value>
public virtual IEnumerable<FunctionArgument> ExpectedArguments { get; }
/// <summary> Gets the return value. </summary>
/// <value> The return value. </value>
/// <summary> Gets the return type produced by the function. </summary>
/// <value>
/// The expected return value type. The default is <see cref="FunctionValue.NUMBER"/>.
/// </value>
public virtual FunctionValue ReturnValue
{
get
{
return FunctionValue.NUMBER;
}
}
/// <summary> Checks the provided arguments to ensure the function contract is honored. </summary>
/// <param name="args"> A variable-length parameters list containing arguments. </param>
/// <returns> True if it succeeds, false if it fails. </returns>
/// <summary>
/// Determines whether the supplied arguments satisfy the function's expected signature.
/// </summary>
/// <param name="args"> The evaluated arguments supplied to the function. </param>
/// <returns>
/// <see langword="true"/> if the supplied arguments match the expected count and value types;
/// otherwise, <see langword="false"/>.
/// </returns>
public bool ArgumentCheck(params FunctionArgument[] args)
{
// Top level sanity checks.
@ -57,10 +69,14 @@ namespace CSMic.StandardLibrary.Functions
return true;
}
/// <summary> Executes a standard library function. </summary>
/// <param name="args"> A variable-length parameters list containing arguments. </param>
/// <param name="action"> The functions action body. </param>
/// <returns> A <see cref="FunctionValue"/>. </returns>
/// <summary> Validates and executes a standard-library function body. </summary>
/// <param name="args"> The evaluated arguments supplied to the function. </param>
/// <param name="action"> The function implementation to execute after argument validation
/// succeeds. </param>
/// <returns>
/// The result returned by <paramref name="action"/>, or <see cref="FunctionValue.NONE"/> if
/// validation fails or execution throws an exception.
/// </returns>
public FunctionValue Execute(FunctionArgument[] args, Func<FunctionArgument[], FunctionValue> action)
{
if (!ArgumentCheck(args))

38
src/StandardLibrary/functions/Sign.cs
View file

@ -3,7 +3,16 @@
namespace CSMic.StandardLibrary.Functions
{
/// <summary> A function that returns <c>1</c> if the expression is positive and <c>-1</c> if it is negative. </summary>
/// <summary>
/// Represents the standard-library <c>sign</c> function.
/// </summary>
/// <remarks>
/// The <c>sign</c> function evaluates a numeric expression and returns:
/// <list type="bullet">
/// <item><description><c>1</c> when the value is greater than or equal to zero.</description></item>
/// <item><description><c>-1</c> when the value is less than zero.</description></item>
/// </list>
/// </remarks>
public class Sign : FunctionBase, ICodedFunction
{
/// <summary> (Immutable) The return value representing "positive". </summary>
@ -11,8 +20,10 @@ namespace CSMic.StandardLibrary.Functions
/// <summary> (Immutable) The return value representing "negative". </summary>
private const decimal NEGATIVE = -1;
/// <summary> Gets the name of the function. </summary>
/// <value> sign. </value>
/// <summary>
/// Gets the expression-language name used to invoke this function.
/// </summary>[
/// <value><c>sign</c>.</value>
public string Name
{
get
@ -21,8 +32,12 @@ namespace CSMic.StandardLibrary.Functions
}
}
/// <summary> Gets the expected arguments. </summary>
/// <value> The expected arguments. </value>
/// <summary>
/// Gets the argument signature expected by the <c>sign</c> function.
/// </summary>
/// <value>
/// A single numeric argument named <c>value</c>.
/// </value>
public override IEnumerable<FunctionArgument> ExpectedArguments
{
get
@ -31,9 +46,16 @@ namespace CSMic.StandardLibrary.Functions
}
}
/// <summary> Executes the function with the given arguments. </summary>
/// <param name="args"> A variable-length parameters list containing arguments. </param>
/// <returns> A <see cref="FunctionValue"/> representing the result of the function execution. </returns>
/// <summary>
/// Executes the <c>sign</c> function.
/// </summary>
/// <param name="args">
/// The evaluated arguments supplied to the function. Exactly one numeric argument is expected.
/// </param>
/// <returns>
/// A numeric <see cref="FunctionValue"/> containing <c>1</c> when the input value is greater than
/// or equal to zero; otherwise <c>-1</c>.
/// </returns>
public FunctionValue Execute(params FunctionArgument[] args)
{
return base.Execute(args, (_args) =>