docs: improve documentation

Signed-off-by: Marcos Tischer Vallim <tischer@gmail.com>

Author: mvallim

.opencode/skills/java-docs/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: java-docs
+description: 'Ensure that Java types are documented with Javadoc comments and follow best practices for documentation.'
+---
+
+# Javadoc Skill
+
+## 🎯 **Skill Overview**
+This skill enables the creation and maintenance of comprehensive Javadoc documentation for Java codebases, ensuring professional code documentation standards.
+
+## 📋 **Skill Details**
+
+### 🔧 **Core Competencies**
+- **Javadoc Generation**: Create comprehensive documentation using Javadoc comments
+- **Code Documentation**: Document methods, and interfaces with proper tags
+- **Standard Compliance**: Follow Javadoc conventions and best practices
+- **Tool Integration**: Generate documentation using javadoc tool and IDE integration
+
+### 📝 **Technical Requirements**
+
+#### **Basic Javadoc Structure**
+```java
+public class MyClass {
+    /**
+     * Method description
+     * @param parameter Description of parameter
+     * @return Description of return value
+     * @throws Exception Description of exception
+     */
+    public void myMethod(String parameter) throws Exception {
+        // implementation
+    }
+}
+```
+
+#### **Required Javadoc Tags**
+- `@param` - Parameter descriptions
+- `@return` - Return value description
+- `@throws` - Exception descriptions
+- `@see` - Related documentation
+- `@deprecated` - Deprecation notice
+
+### 🎯 **Performance Indicators**
+
+#### **Mastery Levels**
+- **Beginner**: Basic Javadoc comments for public methods
+- **Intermediate**: Complete method documentation with all required tags
+- **Advanced**: Professional documentation with cross-references and examples
+
+#### **Quality Metrics**
+- 100% of public methods documented
+- Proper use of all required Javadoc tags
+- Consistent documentation style
+- No missing or incomplete documentation
+
+### 🛠️ **Implementation Process**
+
+#### **Step 1: Method Documentation**
+```java
+/**
+ * Creates a new user account
+ * @param username the user's username
+ * @param email the user's email address
+ * @return the created user object
+ * @throws IllegalArgumentException when username or email is null
+ * @throws UserCreationException when user creation fails
+ */
+public User createUser(String username, String email) 
+    throws IllegalArgumentException, UserCreationException {
+    // implementation
+}
+```
+
+### 📊 **Skill Validation**
+
+#### **Checklist**
+- [ ] All public methods have Javadoc
+- [ ] Required tags are present
+- [ ] Documentation is clear and concise
+- [ ] Examples are provided when needed
+- [ ] Cross-references are included appropriately
+
+#### **Quality Standards**
+- Documentation must be written in English
+- Use proper grammar and spelling
+- Maintain consistent formatting
+- Include relevant examples
+- Update documentation with code changes
+
+### 📈 **Skill Progression**
+
+#### **Level 1: Complete Documentation**
+- Document all public API
+- Include parameter and return descriptions
+- Add exception documentation
+
+#### **Level 2: Professional Documentation**
+- Advanced cross-references
+- Code examples
+- Comprehensive coverage
+- Integration with documentation tools
+
+### 🎯 **Best Practices**
+
+#### **Documentation Standards**
+1. **Clarity**: Write clear, concise descriptions
+2. **Consistency**: Maintain uniform style throughout
+3. **Completeness**: Include all required information
+4. **Accuracy**: Keep documentation updated with code changes
+5. **Readability**: Use proper formatting and structure
+
+#### **Tools Integration**
+- IDE auto-completion support
+- Documentation generation tools
+- Continuous integration integration
+- Version control integration
+
+### 📚 **Resources**
+
+#### **Reference Materials**
+- Oracle Javadoc Documentation
+- Java Language Specification
+- Code style guidelines
+- Project documentation standards
+
+#### **Training Resources**
+- Javadoc tutorial examples
+- Documentation style guides
+- Code review checklists
+- Best practice workshops
+
+### 🎯 **Expected Outcomes**
+- Professional quality code documentation
+- Maintainable and readable documentation
+- Consistent documentation standards
+- Improved code understanding and maintenance
+- Better collaboration among development teams
+
+## 🎯 **Skill Assessment**
+
+### **Evaluation Criteria**
+- Documentation completeness
+- Tag usage accuracy
+- Code clarity and quality
+- Tool integration effectiveness
+- Consistency across codebase
+
+### **Success Metrics**
+- 95%+ documentation coverage
+- Zero missing required tags
+- Positive code review feedback
+- Successful tool integration
+- Team adoption rate

src/main/java/br/com/fluentvalidator/Validator.java

@@ -26,99 +26,198 @@
 import br.com.fluentvalidator.rule.Rule;
 import br.com.fluentvalidator.transform.ValidationResultTransform;
 
+/**
+ * Interface that defines the contract for fluent validators.
+ * <p>
+ * This interface extends {@link Rule} and provides methods for building and executing
+ * validation rules in a fluent, chainable manner. It supports validation of single objects,
+ * collections of objects, and provides flexible result transformation capabilities.
+ * </p>
+ * <p>
+ * Implementations should define validation rules by implementing the {@link #rules()} method
+ * and using the fluent API provided by {@link #ruleFor(Function)} and {@link #ruleForEach(Function)}
+ * to build validation constraints.
+ * </p>
+ * <p>
+ * This interface supports:
+ * <ul>
+ *   <li>Single object validation with {@link #validate(Object)}</li>
+ *   <li>Collection validation with {@link #validate(Collection)}</li>
+ *   <li>Result transformation for custom output formats</li>
+ *   <li>Fail-fast validation mode</li>
+ *   <li>Contextual property storage and retrieval</li>
+ * </ul>
+ * </p>
+ *
+ * @param <T> the type of object being validated
+ */
 public interface Validator<T> extends Rule<T> {
 
   /**
-   *
+   * Defines the validation rules for this validator.
+   * <p>
+   * Subclasses should implement this method to define validation rules using
+   * the fluent API provided by {@link #ruleFor(Function)} and {@link #ruleForEach(Function)}.
+   * This method is called once during initialization in a thread-safe manner.
+   * </p>
    */
   void rules();
 
   /**
-   *
+   * Configures this validator to use fail-fast rule processing.
+   * <p>
+   * When fail-fast mode is enabled, validation will stop at the first rule failure
+   * instead of continuing to evaluate all rules. This can improve performance when
+   * early validation failure is acceptable.
+   * </p>
    */
   void failFastRule();
 
   /**
+   * Returns the current validation counter.
+   * <p>
+   * The counter tracks the number of validation operations or rules that have been
+   * processed. This can be useful for debugging, monitoring, or performance analysis.
+   * </p>
    *
-   * @return Current count element on collection
+   * @return the current counter value, or null if no counter is available
    */
   Integer getCounter();
 
   /**
+   * Sets a property name to be used in the validation context.
+   * <p>
+   * This property name will be associated with the validated object in the validation
+   * context, allowing rules to access contextual information during validation.
+   * </p>
    *
-   * @param property
+   * @param property the property name to set in the validation context
    */
   void setPropertyOnContext(final String property);
 
   /**
+   * Retrieves a property value from the validation context.
+   * <p>
+   * This method allows access to contextual information that was previously stored
+   * in the validation context, enabling rules to make decisions based on broader
+   * validation state.
+   * </p>
    *
-   * @param property
-   * @param clazz
-   * @return
+   * @param <P> the type of the property value
+   * @param property the name of the property to retrieve
+   * @param clazz the class type of the property value
+   * @return the property value cast to the specified type, or null if not found
    */
   <P> P getPropertyOnContext(final String property, final Class<P> clazz);
 
   /**
+   * Validates a single instance and returns the validation result.
+   * <p>
+   * This method processes the given instance through all configured validation rules
+   * and returns a comprehensive result containing any validation errors or success indicators.
+   * </p>
    *
-   * @param instance
-   * @return
+   * @param instance the object instance to validate
+   * @return a ValidationResult containing the outcome of validation
    */
   ValidationResult validate(final T instance);
 
   /**
+   * Validates a single instance and transforms the result using the provided transformer.
+   * <p>
+   * This method combines validation with result transformation in a single operation,
+   * allowing for custom result formats or processing without intermediate objects.
+   * </p>
    *
-   * @param instance
-   * @param transform
-   * @return
+   * @param <E> the type of the transformed result
+   * @param instance the object instance to validate
+   * @param transform the transformer to apply to the validation result
+   * @return the transformed validation result
    */
   <E> E validate(final T instance, final ValidationResultTransform<E> transform);
 
   /**
+   * Validates a collection of instances and returns a list of validation results.
+   * <p>
+   * Each instance in the collection is validated independently, and the results are
+   * collected into a list. The order of results corresponds to the order of instances
+   * in the input collection.
+   * </p>
    *
-   * @param instances
-   * @return
+   * @param instances the collection of instances to validate
+   * @return a list of ValidationResult objects, one for each input instance
    */
   List<ValidationResult> validate(final Collection<T> instances);
 
   /**
+   * Validates a collection of instances and transforms each result using the provided transformer.
+   * <p>
+   * This method combines collection validation with result transformation, applying
+   * the transformer to each individual validation result.
+   * </p>
    *
-   * @param instances
-   * @param transform
-   * @return
+   * @param <E> the type of the transformed results
+   * @param instances the collection of instances to validate
+   * @param transform the transformer to apply to each validation result
+   * @return a list of transformed validation results
    */
   <E> List<E> validate(final Collection<T> instances, final ValidationResultTransform<E> transform);
 
   /**
+   * Creates a validation rule for a specific property of the validated object.
+   * <p>
+   * This method starts a fluent chain for defining validation rules that apply to a
+   * property extracted from the validated object using the provided function. The property
+   * name will be automatically derived from the function if possible.
+   * </p>
    *
-   * @param <P>
-   * @param function
-   * @return
+   * @param <P> the type of the property being validated
+   * @param function a function that extracts the property value from the validated object
+   * @return a RuleBuilderProperty for chaining additional validation constraints
    */
   <P> RuleBuilderProperty<T, P> ruleFor(final Function<T, P> function);
 
   /**
+   * Creates a validation rule for a named property of the validated object.
+   * <p>
+   * This method starts a fluent chain for defining validation rules that apply to a
+   * property extracted from the validated object. The field name is explicitly provided
+   * and will be used in error messages and validation context.
+   * </p>
    *
-   * @param <P>
-   * @param fieldName
-   * @param function
-   * @return
+   * @param <P> the type of the property being validated
+   * @param fieldName the name of the field being validated (used in error messages)
+   * @param function a function that extracts the property value from the validated object
+   * @return a RuleBuilderProperty for chaining additional validation constraints
    */
   <P> RuleBuilderProperty<T, P> ruleFor(final String fieldName, final Function<T, P> function);
 
   /**
+   * Creates validation rules for each element in a collection property.
+   * <p>
+   * This method starts a fluent chain for defining validation rules that apply to each
+   * element of a collection extracted from the validated object. The field name will be
+   * automatically derived from the function if possible.
+   * </p>
    *
-   * @param <P>
-   * @param function
-   * @return
+   * @param <P> the type of elements in the collection being validated
+   * @param function a function that extracts the collection from the validated object
+   * @return a RuleBuilderCollection for chaining additional validation constraints
    */
   <P> RuleBuilderCollection<T, P> ruleForEach(final Function<T, Collection<P>> function);
 
   /**
+   * Creates validation rules for each element in a collection property.
+   * <p>
+   * This method starts a fluent chain for defining validation rules that apply to each
+   * element of a collection extracted from the validated object. The field name is
+   * explicitly provided for error reporting.
+   * </p>
    *
-   * @param <P>
-   * @param fieldName
-   * @param function
-   * @return
+   * @param <P> the type of elements in the collection being validated
+   * @param fieldName the name of the collection field being validated
+   * @param function a function that extracts the collection from the validated object
+   * @return a RuleBuilderCollection for chaining additional validation constraints
    */
   <P> RuleBuilderCollection<T, P> ruleForEach(final String fieldName, final Function<T, Collection<P>> function);
 }