Docs

Author: martijn00

lib/src/bool/has_special_chars_validator.dart

@@ -1,7 +1,20 @@
 import '../../localization/l10n.dart';
 import '../base_validator.dart';
 
+/// {@template has_special_chars_template}
+/// [HasSpecialCharsValidator] extends [BaseValidator] to validate if a string
+/// contains a specified minimum number of special characters.
+///
+/// ## Parameters:
+///
+/// - [atLeast] The minimum number of special characters required.
+/// - [regex] The regular expression used to identify special characters.
+/// - [errorText] The error message returned if the validation fails.
+///
+/// {@macro special_chars_template}
+/// {@endtemplate}
 class HasSpecialCharsValidator extends BaseValidator<String> {
+  /// Constructor for the special characters validator.
   HasSpecialCharsValidator({
     this.atLeast = 1,
 
@@ -15,8 +28,10 @@ class HasSpecialCharsValidator extends BaseValidator<String> {
     super.checkNullOrEmpty,
   }) : regex = regex ?? _specialChar;
 
+  /// The minimum number of special characters required.
   final int atLeast;
 
+  /// The regular expression used to identify special characters.
   final RegExp regex;
 
   @override
@@ -38,6 +53,13 @@ class HasSpecialCharsValidator extends BaseValidator<String> {
     return specialCharLength(valueCandidate) >= atLeast ? null : errorText;
   }
 
+  /// Calculates the number of special characters in the given value.
+  ///
+  /// ## Parameters:
+  /// - [value] The string to be evaluated.
+  ///
+  /// ## Returns:
+  /// The count of special characters in the string.
   int specialCharLength(String value) {
     return regex.allMatches(value).length;
   }

lib/src/bool/has_uppercase_chars_validator.dart

@@ -1,7 +1,20 @@
 import '../../localization/l10n.dart';
 import '../base_validator.dart';
 
+/// {@template has_uppercase_chars_template}
+/// [HasUppercaseCharsValidator] extends [BaseValidator] to validate if a string
+/// contains a specified minimum number of uppercase characters.
+///
+/// ## Parameters:
+///
+/// - [atLeast] The minimum number of uppercase characters required.
+/// - [regex] The regular expression used to identify uppercase characters.
+/// - [errorText] The error message returned if the validation fails.
+///
+/// {@macro upper_case_template}
+/// {@endtemplate}
 class HasUppercaseCharsValidator extends BaseValidator<String> {
+  /// Constructor for the uppercase characters validator.
   HasUppercaseCharsValidator({
     this.atLeast = 1,
 
@@ -15,21 +28,23 @@ class HasUppercaseCharsValidator extends BaseValidator<String> {
     super.checkNullOrEmpty,
   }) : regex = regex ?? _upperCase;
 
+  /// The minimum number of uppercase characters required.
   final int atLeast;
 
+  /// The regular expression used to identify uppercase characters.
   final RegExp regex;
 
   @override
   String get translatedErrorText =>
       FormBuilderLocalizations.current.containsUppercaseCharErrorText(atLeast);
 
   /// {@template upper_case_template}
-  /// This regex matches any character that is not an uppercase letter (A-Z).
+  /// This regex matches any character that is an uppercase letter (A-Z).
   ///
-  /// - It includes special characters, digits, and lowercase letters.
-  /// - It can be used to find non-uppercase characters.
+  /// - It includes all uppercase letters.
+  /// - It can be used to find uppercase characters.
   ///
-  /// Examples: a, 1, @
+  /// Examples: A, B, C
   /// {@endtemplate}
   static final RegExp _upperCase = RegExp('[A-Z]');
 
@@ -38,6 +53,13 @@ class HasUppercaseCharsValidator extends BaseValidator<String> {
     return uppercaseCharLength(valueCandidate) >= atLeast ? null : errorText;
   }
 
+  /// Calculates the number of uppercase characters in the given value.
+  ///
+  /// ## Parameters:
+  /// - [value] The string to be evaluated.
+  ///
+  /// ## Returns:
+  /// The count of uppercase characters in the string.
   int uppercaseCharLength(String value) {
     return regex.allMatches(value).length;
   }

lib/src/bool/is_false_validator.dart

@@ -1,7 +1,17 @@
 import '../../localization/l10n.dart';
 import '../base_validator.dart';
 
+/// {@template is_false_validator_template}
+/// [IsFalseValidator] extends [BaseValidator] to validate if a boolean value is false.
+///
+/// ## Parameters:
+///
+/// - [errorText] The error message returned if the validation fails.
+/// - [checkNullOrEmpty] Whether to check if the value is null or empty.
+///
+/// {@endtemplate}
 class IsFalseValidator extends BaseValidator<bool> {
+  /// Constructor for the false value validator.
   const IsFalseValidator({
     /// {@macro base_validator_error_text}
     super.errorText,

lib/src/bool/is_true_validator.dart

@@ -1,7 +1,17 @@
 import '../../localization/l10n.dart';
 import '../base_validator.dart';
 
+/// {@template is_true_validator_template}
+/// [IsTrueValidator] extends [BaseValidator] to validate if a boolean value is true.
+///
+/// ## Parameters:
+///
+/// - [errorText] The error message returned if the validation fails.
+/// - [checkNullOrEmpty] Whether to check if the value is null or empty.
+///
+/// {@endtemplate}
 class IsTrueValidator extends BaseValidator<bool> {
+  /// Constructor for the true value validator.
   const IsTrueValidator({
     /// {@macro base_validator_error_text}
     super.errorText,

lib/src/collection/contains_element_validator.dart

@@ -1,7 +1,19 @@
 import '../../localization/l10n.dart';
 import '../base_validator.dart';
 
+/// {@template contains_element_validator_template}
+/// [ContainsElementValidator] extends [BaseValidator] to validate if a value is
+/// contained within a specified list of values.
+///
+/// ## Parameters:
+///
+/// - [values] The list of values to check against.
+/// - [errorText] The error message returned if the validation fails.
+/// - [checkNullOrEmpty] Whether to check if the value is null or empty.
+///
+/// {@endtemplate}
 class ContainsElementValidator<T> extends BaseValidator<T> {
+  /// Constructor for the contains element validator.
   const ContainsElementValidator(
     this.values, {
     /// {@macro base_validator_error_text}
@@ -11,6 +23,7 @@ class ContainsElementValidator<T> extends BaseValidator<T> {
     super.checkNullOrEmpty,
   });
 
+  /// The list of values to check against.
   final List<T> values;
 
   @override

lib/src/collection/equal_length_validator.dart

@@ -1,7 +1,21 @@
 import '../../localization/l10n.dart';
 import '../base_validator.dart';
 
+/// {@template equal_length_validator_template}
+/// [EqualLengthValidator] extends [BaseValidator] to validate if a value has a specified length.
+///
+/// This validator works with various types, including String, Iterable, and Map.
+///
+/// ## Parameters:
+///
+/// - [length] The exact length the value should have.
+/// - [allowEmpty] Whether to allow empty values.
+/// - [errorText] The error message returned if the validation fails.
+/// - [checkNullOrEmpty] Whether to check if the value is null or empty.
+///
+/// {@endtemplate}
 class EqualLengthValidator<T> extends BaseValidator<T> {
+  /// Constructor for the equal length validator.
   const EqualLengthValidator(
     this.length, {
     this.allowEmpty = false,
@@ -13,8 +27,10 @@ class EqualLengthValidator<T> extends BaseValidator<T> {
     super.checkNullOrEmpty,
   });
 
+  /// The exact length the value should have.
   final int length;
 
+  /// Whether to allow empty values.
   final bool allowEmpty;
 
   @override

lib/src/collection/max_length_validator.dart

@@ -1,7 +1,20 @@
 import '../../localization/l10n.dart';
 import '../base_validator.dart';
 
+/// {@template max_length_validator_template}
+/// [MaxLengthValidator] extends [BaseValidator] to validate if a value does not exceed a specified maximum length.
+///
+/// This validator works with various types, including String, Iterable, and Map.
+///
+/// ## Parameters:
+///
+/// - [maxLength] The maximum length the value is allowed to have.
+/// - [errorText] The error message returned if the validation fails.
+/// - [checkNullOrEmpty] Whether to check if the value is null or empty.
+///
+/// {@endtemplate}
 class MaxLengthValidator<T> extends BaseValidator<T> {
+  /// Constructor for the maximum length validator.
   const MaxLengthValidator(
     this.maxLength, {
     /// {@macro base_validator_error_text}
@@ -11,6 +24,7 @@ class MaxLengthValidator<T> extends BaseValidator<T> {
     super.checkNullOrEmpty,
   });
 
+  /// The maximum length the value is allowed to have.
   final int maxLength;
 
   @override

lib/src/collection/min_length_validator.dart

@@ -1,7 +1,20 @@
 import '../../localization/l10n.dart';
 import '../base_validator.dart';
 
+/// {@template min_length_validator_template}
+/// [MinLengthValidator] extends [BaseValidator] to validate if a value meets a specified minimum length.
+///
+/// This validator works with various types, including String, Iterable, and Map.
+///
+/// ## Parameters:
+///
+/// - [minLength] The minimum length the value is required to have.
+/// - [errorText] The error message returned if the validation fails.
+/// - [checkNullOrEmpty] Whether to check if the value is null or empty.
+///
+/// {@endtemplate}
 class MinLengthValidator<T> extends BaseValidator<T> {
+  /// Constructor for the minimum length validator.
   const MinLengthValidator(
     this.minLength, {
     /// {@macro base_validator_error_text}
@@ -11,6 +24,7 @@ class MinLengthValidator<T> extends BaseValidator<T> {
     super.checkNullOrEmpty,
   });
 
+  /// The minimum length the value is required to have.
   final int minLength;
 
   @override

lib/src/collection/range_validator.dart

@@ -1,6 +1,23 @@
 import '../../form_builder_validators.dart';
 
+/// {@template range_validator_template}
+/// [RangeValidator] extends [BaseValidator] to validate if a value falls within a specified range.
+///
+/// This validator works with various types, including numeric types and collections.
+///
+/// ## Parameters:
+///
+/// - [min] The minimum value of the range.
+/// - [max] The maximum value of the range.
+/// - [inclusive] Whether the range is inclusive of the min and max values.
+/// - [errorText] The error message returned if the validation fails.
+/// - [checkNullOrEmpty] Whether to check if the value is null or empty.
+///
+/// This validator uses [MinValidator], [MaxValidator], [MinLengthValidator], and [MaxLengthValidator] internally.
+///
+/// {@endtemplate}
 class RangeValidator<T> extends BaseValidator<T> {
+  /// Constructor for the range validator.
   RangeValidator(
     this.min,
     this.max, {
@@ -34,18 +51,25 @@ class RangeValidator<T> extends BaseValidator<T> {
           checkNullOrEmpty: checkNullOrEmpty,
         );
 
+  /// The minimum value of the range.
   final num min;
 
+  /// The maximum value of the range.
   final num max;
 
+  /// Whether the range is inclusive of the min and max values.
   final bool inclusive;
 
+  /// Internal minimum value validator.
   final MinValidator<T> _minValidator;
 
+  /// Internal maximum value validator.
   final MaxValidator<T> _maxValidator;
 
+  /// Internal minimum length validator.
   final MinLengthValidator<T> _minLengthValidator;
 
+  /// Internal maximum length validator.
   final MaxLengthValidator<T> _maxLengthValidator;
 
   @override

lib/src/collection/unique_validator.dart

@@ -1,7 +1,18 @@
 import '../../localization/l10n.dart';
 import '../base_validator.dart';
 
+/// {@template unique_validator_template}
+/// [UniqueValidator] extends [BaseValidator] to validate if a value is unique within a specified list of values.
+///
+/// ## Parameters:
+///
+/// - [values] The list of values to check against for uniqueness.
+/// - [errorText] The error message returned if the validation fails.
+/// - [checkNullOrEmpty] Whether to check if the value is null or empty.
+///
+/// {@endtemplate}
 class UniqueValidator<T> extends BaseValidator<T> {
+  /// Constructor for the unique value validator.
   const UniqueValidator(
     this.values, {
     /// {@macro base_validator_error_text}
@@ -11,6 +22,7 @@ class UniqueValidator<T> extends BaseValidator<T> {
     super.checkNullOrEmpty,
   });
 
+  /// The list of values to check against for uniqueness.
   final List<T> values;
 
   @override