Document. Minor refactor.

Author: sharpjs

PSql.Tests/Tests.Unit/NewSqlContextCommandTests.cs

@@ -172,8 +172,8 @@ public void ServerName_Override_Valid(string expression, string? value)
 
     public static IEnumerable<Case> InvalidPortCases = new[]
     {
-        new Case("''",    @"Cannot validate argument on parameter 'ServerPort'. The value ""0"" is not a positive number."),
-        new Case("0",     @"Cannot validate argument on parameter 'ServerPort'. The value ""0"" is not a positive number."),
+        new Case("''",    @"Cannot validate argument on parameter 'ServerPort'. The value ""0"" is not a number between 1 and 65535, inclusive."),
+        new Case("0",     @"Cannot validate argument on parameter 'ServerPort'. The value ""0"" is not a number between 1 and 65535, inclusive."),
         new Case("-1",    @"Cannot bind parameter 'ServerPort'. Cannot convert value """ +    @"-1"" to type ""System.UInt16"". Error: ""Value was either too large or too small for a UInt16."""),
         new Case("65536", @"Cannot bind parameter 'ServerPort'. Cannot convert value """ + @"65536"" to type ""System.UInt16"". Error: ""Value was either too large or too small for a UInt16.""")
     };

PSql/Metadata/ValidateNullOrPositiveUInt16Attribute.cs

@@ -1,26 +1,33 @@
 // Copyright Subatomix Research Inc.
 // SPDX-License-Identifier: MIT
 
-// TODO: Document
-#pragma warning disable CS1591
-
 namespace PSql;
 
+/// <summary>
+///   Validates that a parameter is either <see langword="null"/> or a positive
+///   <see langword="ushort"/> value.
+/// </summary>
+/// <remarks>
+///   Valid values range from <c>1</c> to <c>65535</c>.
+/// </remarks>
 public class ValidateNullOrPositiveUInt16Attribute : ValidateArgumentsAttribute
 {
-    protected override void Validate(object arg, EngineIntrinsics engine)
+    /// <inheritdoc/>
+    protected override void Validate(object arguments, EngineIntrinsics engineIntrinsics)
     {
-        if (arg is null)
+        // NOTE: 'arguments' is a single argument, despite the plural name.
+
+        if (arguments is null)
             return;
 
-        if (arg is PSObject psObject)
-            arg = psObject.BaseObject;
+        if (arguments is PSObject psObject)
+            arguments = psObject.BaseObject;
 
-        var value = LanguagePrimitives.ConvertTo<ushort>(arg);
+        var value = LanguagePrimitives.ConvertTo<ushort>(arguments);
 
         if (value < 1)
             throw new ValidationMetadataException(string.Format(
-                @"The value ""{0}"" is not a positive number.", arg
+                @"The value ""{0}"" is not a number between 1 and 65535, inclusive.", arguments
             ));
     }
 }

PSql/Metadata/ValidateNullOrTimeoutAttribute.cs

@@ -1,36 +1,43 @@
 // Copyright Subatomix Research Inc.
 // SPDX-License-Identifier: MIT
 
-// TODO: Document
-#pragma warning disable CS1591
-
 namespace PSql;
 
+/// <summary>
+///   Validates that a parameter is either <see langword="null"/> or a valid
+///   timeout value.
+/// </summary>
+/// <remarks>
+///   Valid timeouts range from <c>00:00:00</c> to <c>24855.03:14:07</c>.
+/// </remarks>
 public class ValidateNullOrTimeoutAttribute : ValidateArgumentsAttribute
 {
     private const long
-        MinValueTicks =                  0L,
-        MaxValueTicks = 2147483647_0000000L;
+        MinValueTicks =            0 * TimeSpan.TicksPerSecond, //       00:00:00
+        MaxValueTicks = int.MaxValue * TimeSpan.TicksPerSecond; // 24855.03:14:07
 
-    protected override void Validate(object arg, EngineIntrinsics engine)
+    /// <inheritdoc/>
+    protected override void Validate(object arguments, EngineIntrinsics engineIntrinsics)
     {
-        if (arg is null)
+        // NOTE: 'arguments' is a single argument, despite the plural name.
+
+        if (arguments is null)
             return;
 
-        if (arg is PSObject psObject)
-            arg = psObject.BaseObject;
+        if (arguments is PSObject psObject)
+            arguments = psObject.BaseObject;
 
-        var value = LanguagePrimitives.ConvertTo<TimeSpan>(arg);
+        var value = LanguagePrimitives.ConvertTo<TimeSpan>(arguments);
         var ticks = value.Ticks;
 
         if (ticks < MinValueTicks)
             throw new ValidationMetadataException(string.Format(
-                @"The value ""{0}"" is negative. Negative timeouts are not supported.", arg
+                @"The value ""{0}"" is negative. Negative timeouts are not supported.", arguments
             ));
 
         if (ticks > MaxValueTicks)
             throw new ValidationMetadataException(string.Format(
-                @"The value ""{0}"" exceeds the maximum supported timeout, 24855.03:14:07.", arg
+                @"The value ""{0}"" exceeds the maximum supported timeout, 24855.03:14:07.", arguments
             ));
     }
 }