From 8e07c48c35aadd613f884a1230d500cf431a2d05 Mon Sep 17 00:00:00 2001
From: Jacob Moura <jacobaraujo7@gmail.com>
Date: Sat, 24 Aug 2024 17:06:59 -0300
Subject: [PATCH] update doc

---
 lib/src/validator_builder.dart | 23 ++++++++++++++++++++++-
 1 file changed, 22 insertions(+), 1 deletion(-)

diff --git a/lib/src/validator_builder.dart b/lib/src/validator_builder.dart
index 5e436f2..ff737d1 100644
--- a/lib/src/validator_builder.dart
+++ b/lib/src/validator_builder.dart
@@ -87,7 +87,28 @@ class LucidValidationBuilder<TProp, Entity> {
     return this;
   }
 
-  /// Changes the cascade mode for this validation.
+  /// Sets the [CascadeMode] for the validation rules associated with this property.
+  ///
+  /// The [cascade] method allows you to control the behavior of rule execution when a validation failure occurs.
+  /// By default, all validation rules are executed even if one fails. However, by setting the [CascadeMode],
+  /// you can specify whether validation should stop after the first failure (`CascadeMode.stopOnFirstFailure`)
+  /// or continue executing all rules (`CascadeMode.continueExecution`).
+  ///
+  /// [mode] is the [CascadeMode] that determines whether to continue or stop validation after a failure.
+  ///
+  /// Returns the [LucidValidationBuilder] to allow for method chaining.
+  ///
+  /// Example:
+  /// ```dart
+  /// ruleFor((user) => user.password, key: 'password')
+  ///     .notEmpty()
+  ///     .minLength(8)
+  ///     .cascade(CascadeMode.stopOnFirstFailure);
+  /// ```
+  ///
+  /// In the example above, if the password is empty, the validation will stop immediately, and the `minLength(8)` rule
+  /// will not be executed. This can be useful for optimizing performance or ensuring that more critical rules are
+  /// evaluated first.
   LucidValidationBuilder<TProp, Entity> cascade(CascadeMode mode) {
     _mode = mode;
     return this;