Polishing XMLDoc conventions

src/StandardLibrary/functions/FunctionBase.cs

@@ -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>
+        /// <summary> Gets the argument signature expected by the function. </summary>
-        /// <value> The expected arguments. </value>
+        /// <value> The ordered collection of arguments required by the function. </value>
         public virtual IEnumerable<FunctionArgument> ExpectedArguments { get; }
 
-        /// <summary> Gets the return value. </summary>
+        /// <summary> Gets the return type produced by the function. </summary>
-        /// <value> The return value. </value>
+        /// <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>
+        /// <summary>
-        /// <param name="args"> A variable-length parameters list containing arguments. </param>
+        ///  Determines whether the supplied arguments satisfy the function's expected signature.
-        /// <returns> True if it succeeds, false if it fails. </returns>
+        /// </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>
+        /// <summary> Validates and executes a standard-library function body. </summary>
-        /// <param name="args"> A variable-length parameters list containing arguments. </param>
+        /// <param name="args"> The evaluated arguments supplied to the function. </param>
-        /// <param name="action"> The functions action body. </param>
+        /// <param name="action"> The function implementation to execute after argument validation
-        /// <returns> A <see cref="FunctionValue"/>. </returns>
+        ///  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))

src/StandardLibrary/functions/Sign.cs

@@ -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>
+        /// <summary>
-        /// <value> sign. </value>
+        /// 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>
+        /// <summary>
-        /// <value> The expected arguments. </value>
+        /// 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>
+        /// <summary>
-        /// <param name="args"> A variable-length parameters list containing arguments. </param>
+        /// Executes the <c>sign</c> function.
-        /// <returns> A <see cref="FunctionValue"/> representing the result of the function execution. </returns>
+        /// </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) =>