docs: add docblocks

Author: Jon Waldstein

src/Rules/Currency.php

@@ -8,6 +8,37 @@
 use StellarWP\Validation\Contracts\ValidatesOnFrontEnd;
 use StellarWP\Validation\Contracts\ValidationRule;
 
+/**
+ * Currency validation rule.
+ *
+ * Validates that a value is a valid 3-letter currency code. Supports both ISO 4217
+ * standard currency codes and custom currency codes (like cryptocurrencies).
+ *
+ * Features:
+ * - Case-insensitive validation
+ * - Complete ISO 4217 currency code support (169 codes as of 2024)
+ * - Support for custom currency codes
+ * - Option to combine custom codes with ISO codes
+ * - Includes commonly used non-ISO codes (GGP, IMP, JEP, TVD)
+ *
+ * @example Basic usage with default ISO codes:
+ * $rule = new Currency();
+ * // Validates: USD, EUR, JPY, GBP, etc.
+ *
+ * @example Custom codes only:
+ * $rule = new Currency(['BTC', 'ETH', 'XRP']);
+ * // Validates: BTC, ETH, XRP only
+ *
+ * @example Custom codes with ISO codes:
+ * $rule = new Currency(['BTC', 'ETH'], true);
+ * // Validates: BTC, ETH, USD, EUR, JPY, etc.
+ *
+ * @example String configuration:
+ * $rule = Currency::fromString('BTC,ETH,XRP|include_defaults');
+ * // Validates: BTC, ETH, XRP, USD, EUR, JPY, etc.
+ *
+ * @since 1.0.0
+ */
 class Currency implements ValidationRule, ValidatesOnFrontEnd
 {
     /**
@@ -16,7 +47,36 @@ class Currency implements ValidationRule, ValidatesOnFrontEnd
     protected $currencyCodes;
 
     /**
-     * @unreleased
+     * Creates a new Currency validation rule.
+     *
+     * @unreleased Added $includeDefaultCurrencyCodes parameter for enhanced flexibility.
+     *
+     * This rule validates that a value is a valid 3-letter currency code (case-insensitive).
+     * By default, it uses the complete list of ISO 4217 currency codes plus some commonly
+     * used non-ISO codes like GGP, IMP, JEP, and TVD.
+     *
+     * @param array|null $currencyCodes Optional array of custom currency codes to validate against.
+     *                                  If null or empty, uses default ISO 4217 codes.
+     * @param bool $includeDefaultCurrencyCodes Whether to merge custom codes with default ISO codes.
+     *                                          Only applies when $currencyCodes is provided and not empty.
+     *                                          Default: false (use only custom codes).
+     *
+     * @example
+     * // Use default ISO 4217 codes only
+     * $rule = new Currency();
+     * // Validates: USD, EUR, JPY, GBP, etc.
+     *
+     * @example
+     * // Use only custom currency codes
+     * $rule = new Currency(['BTC', 'ETH', 'XRP']);
+     * // Validates: BTC, ETH, XRP only (ISO codes will fail)
+     *
+     * @example
+     * // Use custom codes AND default ISO codes
+     * $rule = new Currency(['BTC', 'ETH', 'XRP'], true);
+     * // Validates: BTC, ETH, XRP, USD, EUR, JPY, GBP, etc.
+     *
+     * @since 1.0.0
      */
     public function __construct(?array $currencyCodes = null, bool $includeDefaultCurrencyCodes = false)
     {
@@ -40,8 +100,45 @@ public static function id(): string
     }
 
     /**
+     * Creates a Currency validation rule from a string configuration.
+     *
      * @inheritDoc
      *
+     * @unreleased Enhanced to support include_defaults syntax for merging custom codes with ISO codes.
+     *
+     * The options string can contain:
+     * - Empty/null: Uses default ISO 4217 currency codes
+     * - Comma-separated codes: Uses only the specified custom codes
+     * - Codes with "|include_defaults": Uses custom codes plus default ISO codes
+     *
+     * @param string|null $options Configuration string in one of these formats:
+     *                            - null or empty: Use default ISO codes
+     *                            - "BTC,ETH,XRP": Use only custom codes
+     *                            - "BTC,ETH,XRP|include_defaults": Use custom + ISO codes
+     *
+     * @return ValidationRule A configured Currency validation rule instance.
+     *
+     * @example
+     * // Use default ISO 4217 codes
+     * $rule = Currency::fromString('');
+     * $rule = Currency::fromString(null);
+     * // Validates: USD, EUR, JPY, GBP, etc.
+     *
+     * @example
+     * // Use only custom cryptocurrency codes
+     * $rule = Currency::fromString('BTC,ETH,XRP,ADA');
+     * // Validates: BTC, ETH, XRP, ADA only (ISO codes will fail)
+     *
+     * @example
+     * // Use custom codes plus all default ISO codes
+     * $rule = Currency::fromString('BTC,ETH,XRP|include_defaults');
+     * // Validates: BTC, ETH, XRP, USD, EUR, JPY, GBP, etc.
+     *
+     * @example
+     * // Single custom code with defaults
+     * $rule = Currency::fromString('GOLD|include_defaults');
+     * // Validates: GOLD, USD, EUR, JPY, GBP, etc.
+     *
      * @since 1.0.0
      */
     public static function fromString(string $options = null): ValidationRule
@@ -68,8 +165,26 @@ public function serializeOption()
     }
 
     /**
+     * Validates that the given value is a valid currency code.
+     *
      * @inheritDoc
      *
+     * Performs case-insensitive validation against the configured currency codes.
+     * The value must be a string and match one of the allowed currency codes.
+     *
+     * @param mixed $value The value to validate (should be a 3-letter currency code string).
+     * @param Closure $fail Callback to call if validation fails.
+     * @param string $key The field name being validated.
+     * @param array $values All field values from the request.
+     *
+     * @example
+     * // These will pass validation (case-insensitive):
+     * // 'USD', 'usd', 'EUR', 'eur', 'JPY', 'jpy'
+     *
+     * @example
+     * // These will fail validation:
+     * // 'US', 'USDD', 'XYZ', 123, null, ''
+     *
      * @since 1.0.0
      */
     public function __invoke($value, Closure $fail, string $key, array $values)