Fixes

Author: martijn00

lib/src/network/mac_address_validator.dart

@@ -1,7 +1,20 @@
 import '../../localization/l10n.dart';
 import '../base_validator.dart';
 
+/// {@template mac_address_validator_template}
+/// [MacAddressValidator] extends [BaseValidator] to validate if a string represents a valid MAC address.
+///
+/// This validator checks if the MAC address matches the specified regex pattern.
+///
+/// ## Parameters:
+///
+/// - [regex] The regular expression used to validate the MAC address format. Defaults to a standard MAC address regex.
+/// - [errorText] The error message returned if the validation fails.
+/// - [checkNullOrEmpty] Whether to check if the value is null or empty.
+///
+/// {@endtemplate}
 class MacAddressValidator extends BaseValidator<String> {
+  /// Constructor for the MAC address validator.
   MacAddressValidator({
     /// {@macro mac_address_template}
     RegExp? regex,
@@ -13,15 +26,16 @@ class MacAddressValidator extends BaseValidator<String> {
     super.checkNullOrEmpty,
   }) : regex = regex ?? _macAddress;
 
+  /// The regular expression used to validate the MAC address format.
   final RegExp regex;
 
   /// {@template mac_address_template}
   /// This regex matches MAC addresses.
   ///
   /// - It consists of six groups of two hexadecimal digits.
-  /// - Each group is separated by a colon.
+  /// - Each group is separated by a colon or hyphen.
   ///
-  /// Examples: 00:1A:2B:3C:4D:5E, 00:1A:2B:3C:4D:5E
+  /// Examples: 00:1A:2B:3C:4D:5E, 00-1A-2B-3C-4D-5E
   /// {@endtemplate}
   static final RegExp _macAddress = RegExp(
     r'^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$|^([0-9A-Fa-f]{4}\.){2}([0-9A-Fa-f]{4})$',

lib/src/network/phone_number_validator.dart

@@ -1,7 +1,20 @@
 import '../../localization/l10n.dart';
 import '../base_validator.dart';
 
+/// {@template phone_number_validator_template}
+/// [PhoneNumberValidator] extends [BaseValidator] to validate if a string represents a valid international phone number.
+///
+/// This validator checks if the phone number matches the specified regex pattern.
+///
+/// ## Parameters:
+///
+/// - [regex] The regular expression used to validate the phone number format. Defaults to a standard international phone number regex.
+/// - [errorText] The error message returned if the validation fails.
+/// - [checkNullOrEmpty] Whether to check if the value is null or empty.
+///
+/// {@endtemplate}
 class PhoneNumberValidator extends BaseValidator<String> {
+  /// Constructor for the phone number validator.
   PhoneNumberValidator({
     /// {@macro phone_number_template}
     RegExp? regex,
@@ -13,6 +26,7 @@ class PhoneNumberValidator extends BaseValidator<String> {
     super.checkNullOrEmpty,
   }) : regex = regex ?? _phoneNumber;
 
+  /// The regular expression used to validate the phone number format.
   final RegExp regex;
 
   /// {@template phone_number_template}

lib/src/network/port_number_validator.dart

@@ -1,7 +1,21 @@
 import '../../localization/l10n.dart';
 import '../base_validator.dart';
 
+/// {@template port_number_validator_template}
+/// [PortNumberValidator] extends [BaseValidator] to validate if a string represents a valid port number.
+///
+/// This validator checks if the port number is an integer within the specified range (0 to 65535 by default).
+///
+/// ## Parameters:
+///
+/// - [min] The minimum allowable port number. Defaults to 0.
+/// - [max] The maximum allowable port number. Defaults to 65535.
+/// - [errorText] The error message returned if the validation fails.
+/// - [checkNullOrEmpty] Whether to check if the value is null or empty.
+///
+/// {@endtemplate}
 class PortNumberValidator extends BaseValidator<String> {
+  /// Constructor for the port number validator.
   PortNumberValidator({
     this.min = 0,
     this.max = 65535,
@@ -13,8 +27,10 @@ class PortNumberValidator extends BaseValidator<String> {
     super.checkNullOrEmpty,
   });
 
+  /// The minimum allowable port number.
   final int min;
 
+  /// The maximum allowable port number.
   final int max;
 
   @override

lib/src/network/url_validator.dart

@@ -1,6 +1,25 @@
 import '../../form_builder_validators.dart';
 
+/// {@template url_validator_template}
+/// [UrlValidator] extends [BaseValidator] to validate if a string represents a valid URL.
+///
+/// This validator checks if the URL matches the specified regex pattern and adheres to various URL validation rules.
+///
+/// ## Parameters:
+///
+/// - [protocols] The list of allowed protocols (e.g., http, https, ftp). Defaults to ['http', 'https', 'ftp'].
+/// - [requireTld] Whether a top-level domain (TLD) is required. Defaults to true.
+/// - [requireProtocol] Whether the protocol is required. Defaults to false.
+/// - [allowUnderscore] Whether underscores are allowed in the URL. Defaults to false.
+/// - [hostWhitelist] A list of valid hostnames that are explicitly allowed.
+/// - [hostBlacklist] A list of invalid hostnames that are explicitly disallowed.
+/// - [regex] The regular expression used to validate the URL format. If provided, overrides the default URL regex.
+/// - [errorText] The error message returned if the validation fails.
+/// - [checkNullOrEmpty] Whether to check if the value is null or empty.
+///
+/// {@endtemplate}
 class UrlValidator extends BaseValidator<String> {
+  /// Constructor for the URL validator.
   UrlValidator({
     this.protocols = const <String>['http', 'https', 'ftp'],
     this.requireTld = true,
@@ -17,22 +36,31 @@ class UrlValidator extends BaseValidator<String> {
     super.checkNullOrEmpty,
   }) : _ipValidator = IpValidator(regex: regex, errorText: errorText);
 
+  /// The list of allowed protocols.
   final List<String> protocols;
 
+  /// Whether a top-level domain (TLD) is required.
   final bool requireTld;
 
+  /// Whether the protocol is required.
   final bool requireProtocol;
 
+  /// Whether underscores are allowed in the URL.
   final bool allowUnderscore;
 
+  /// A list of valid hostnames that are explicitly allowed.
   final List<String> hostWhitelist;
 
+  /// A list of invalid hostnames that are explicitly disallowed.
   final List<String> hostBlacklist;
 
+  /// The regular expression used to validate the URL format.
   final RegExp? regex;
 
+  /// The maximum allowable length for a URL.
   final int _maxUrlLength = 2083;
 
+  /// The IP validator instance used to validate IP addresses within the URL.
   final IpValidator _ipValidator;
 
   @override
@@ -55,7 +83,7 @@ class UrlValidator extends BaseValidator<String> {
         : null;
   }
 
-  /// check if the string [str] is a URL
+  /// Check if the string [str] is a URL.
   ///
   /// * [protocols] sets the list of allowed protocols
   /// * [requireTld] sets if TLD is required
@@ -177,10 +205,10 @@ class UrlValidator extends BaseValidator<String> {
     return true;
   }
 
-  /// check if the string [str] is a fully qualified domain name (e.g. domain.com).
+  /// Check if the string [str] is a fully qualified domain name (e.g., domain.com).
   ///
   /// * [requireTld] sets if TLD is required
-  /// * [allowUnderscore] sets if underscores are allowed
+  /// * [allowUnderscores] sets if underscores are allowed
   bool isFQDN(
     String str, {
     bool requireTld = true,
@@ -212,6 +240,7 @@ class UrlValidator extends BaseValidator<String> {
     return true;
   }
 
+  /// Remove and return the first element from a list.
   T shift<T>(List<T> l) {
     if (l.isNotEmpty) {
       final T first = l.first;

lib/src/numeric/between_validator.dart

@@ -1,7 +1,21 @@
 import '../../localization/l10n.dart';
 import '../base_validator.dart';
 
+/// {@template between_validator_template}
+/// [BetweenValidator] extends [BaseValidator] to validate if a number is within a specified range.
+///
+/// This validator checks if the value is between the minimum and maximum inclusive.
+///
+/// ## Parameters:
+///
+/// - [min] The minimum allowable value.
+/// - [max] The maximum allowable value.
+/// - [errorText] The error message returned if the validation fails.
+/// - [checkNullOrEmpty] Whether to check if the value is null or empty.
+///
+/// {@endtemplate}
 class BetweenValidator extends BaseValidator<num> {
+  /// Constructor for the between validator.
   const BetweenValidator(
     this.min,
     this.max, {
@@ -12,7 +26,10 @@ class BetweenValidator extends BaseValidator<num> {
     super.checkNullOrEmpty,
   });
 
+  /// The minimum allowable value.
   final num min;
+
+  /// The maximum allowable value.
   final num max;
 
   @override

lib/src/numeric/even_number_validator.dart

@@ -1,7 +1,19 @@
 import '../../localization/l10n.dart';
 import '../base_validator.dart';
 
+/// {@template even_number_validator_template}
+/// [EvenNumberValidator] extends [BaseValidator] to validate if a string represents an even number.
+///
+/// This validator checks if the provided string can be parsed into an integer and if that integer is even.
+///
+/// ## Parameters:
+///
+/// - [errorText] The error message returned if the validation fails.
+/// - [checkNullOrEmpty] Whether to check if the value is null or empty.
+///
+/// {@endtemplate}
 class EvenNumberValidator extends BaseValidator<String> {
+  /// Constructor for the even number validator.
   const EvenNumberValidator({
     /// {@macro base_validator_error_text}
     super.errorText,

lib/src/numeric/integer_validator.dart

@@ -1,7 +1,20 @@
 import '../../localization/l10n.dart';
 import '../base_validator.dart';
 
+/// {@template integer_validator_template}
+/// [IntegerValidator] extends [BaseValidator] to validate if a string represents a valid integer.
+///
+/// This validator checks if the provided string can be parsed into an integer with an optional radix.
+///
+/// ## Parameters:
+///
+/// - [radix] The base to use for parsing the integer. Defaults to 10 if not specified.
+/// - [errorText] The error message returned if the validation fails.
+/// - [checkNullOrEmpty] Whether to check if the value is null or empty.
+///
+/// {@endtemplate}
 class IntegerValidator extends BaseValidator<String> {
+  /// Constructor for the integer validator.
   const IntegerValidator({
     this.radix,
 
@@ -12,6 +25,7 @@ class IntegerValidator extends BaseValidator<String> {
     super.checkNullOrEmpty,
   });
 
+  /// The base to use for parsing the integer.
   final int? radix;
 
   @override

lib/src/numeric/max_validator.dart

@@ -1,7 +1,21 @@
 import '../../localization/l10n.dart';
 import '../base_validator.dart';
 
+/// {@template max_validator_template}
+/// [MaxValidator] extends [BaseValidator] to validate if a value is less than or equal to a specified maximum value.
+///
+/// This validator checks if the value is a number or a string that can be parsed into a number and ensures it does not exceed the specified maximum value.
+///
+/// ## Parameters:
+///
+/// - [max] The maximum allowable value.
+/// - [inclusive] Whether the maximum value is inclusive. Defaults to true.
+/// - [errorText] The error message returned if the validation fails.
+/// - [checkNullOrEmpty] Whether to check if the value is null or empty.
+///
+/// {@endtemplate}
 class MaxValidator<T> extends BaseValidator<T> {
+  /// Constructor for the maximum value validator.
   const MaxValidator(
     this.max, {
     this.inclusive = true,
@@ -13,8 +27,10 @@ class MaxValidator<T> extends BaseValidator<T> {
     super.checkNullOrEmpty,
   });
 
+  /// The maximum allowable value.
   final num max;
 
+  /// Whether the maximum value is inclusive.
   final bool inclusive;
 
   @override

lib/src/numeric/min_validator.dart

@@ -1,7 +1,21 @@
 import '../../localization/l10n.dart';
 import '../base_validator.dart';
 
+/// {@template min_validator_template}
+/// [MinValidator] extends [BaseValidator] to validate if a value is greater than or equal to a specified minimum value.
+///
+/// This validator checks if the value is a number or a string that can be parsed into a number and ensures it meets the specified minimum value.
+///
+/// ## Parameters:
+///
+/// - [min] The minimum allowable value.
+/// - [inclusive] Whether the minimum value is inclusive. Defaults to true.
+/// - [errorText] The error message returned if the validation fails.
+/// - [checkNullOrEmpty] Whether to check if the value is null or empty.
+///
+/// {@endtemplate}
 class MinValidator<T> extends BaseValidator<T> {
+  /// Constructor for the minimum value validator.
   const MinValidator(
     this.min, {
     this.inclusive = true,
@@ -13,8 +27,10 @@ class MinValidator<T> extends BaseValidator<T> {
     super.checkNullOrEmpty,
   });
 
+  /// The minimum allowable value.
   final num min;
 
+  /// Whether the minimum value is inclusive.
   final bool inclusive;
 
   @override

lib/src/numeric/negative_number_validator.dart

@@ -1,7 +1,19 @@
 import '../../localization/l10n.dart';
 import '../base_validator.dart';
 
+/// {@template negative_number_validator_template}
+/// [NegativeNumberValidator] extends [BaseValidator] to validate if a value is a negative number.
+///
+/// This validator checks if the value is a number or a string that can be parsed into a number and ensures it is negative.
+///
+/// ## Parameters:
+///
+/// - [errorText] The error message returned if the validation fails.
+/// - [checkNullOrEmpty] Whether to check if the value is null or empty.
+///
+/// {@endtemplate}
 class NegativeNumberValidator<T> extends BaseValidator<T> {
+  /// Constructor for the negative number validator.
   const NegativeNumberValidator({
     /// {@macro base_validator_error_text}
     super.errorText,