javadoc

Author: SentryMan

validator/src/main/java/io/avaje/validation/adapter/MethodAdapterProvider.java

@@ -3,20 +3,58 @@
 import java.lang.reflect.Method;
 import java.util.List;
 
+/**
+ * Provides adapters for method validation, including parameter, return, and cross-parameter adapters.
+ * <p>
+ * Implementations supply the target {@link Method} and adapters for validating method parameters,
+ * return values, and cross-parameter constraints within a validation context.
+ */
 public interface MethodAdapterProvider {
 
+  /**
+   * Returns the target method to be validated.
+   *
+   * @return the {@link Method} instance
+   * @throws Exception if the method cannot be provided
+   */
   Method method() throws Exception;
 
+  /**
+   * Provides adapters for validating each method parameter.
+   *
+   * @param ctx the validation context
+   * @return list of parameter adapters
+   */
   List<ValidationAdapter<Object>> paramAdapters(ValidationContext ctx);
 
+  /**
+   * Provides an adapter for validating the method return value.
+   * Default implementation returns a no-op adapter.
+   *
+   * @param ctx the validation context
+   * @return the return value adapter
+   */
   default ValidationAdapter<Object> returnAdapter(ValidationContext ctx) {
     return ctx.noop();
   }
 
+  /**
+   * Provides an adapter for cross-parameter validation (constraints involving multiple parameters).
+   * Default implementation returns a no-op adapter.
+   *
+   * @param ctx the validation context
+   * @return the cross-parameter adapter
+   */
   default ValidationAdapter<Object[]> crossParamAdapter(ValidationContext ctx) {
     return ctx.noop();
   }
 
+  /**
+   * Provides the target method, wrapping checked exceptions as {@link IllegalStateException}.
+   *
+   * @return the {@link Method} instance
+   * @throws IllegalStateException if the method cannot be provided
+   */
   default Method provide() {
     try {
       return method();

validator/src/main/java/io/avaje/validation/spi/ValidationExtension.java

@@ -2,7 +2,22 @@
 
 import io.avaje.spi.Service;
 
-/** Super interface for all validation SPIs */
+/**
+ * Marker super interface for all validation Service Provider Interfaces (SPIs).
+ *
+ * <p>Implementations of this interface extend the validation system with custom adapters,
+ * annotation handling, message interpolation, and other validation-related features.
+ *
+ * <p>Permitted subtypes include:
+ *
+ * <ul>
+ *   <li>{@link AdapterFactory} - Provides adapters for validation logic.
+ *   <li>{@link AnnotationFactory} - Provides adapters for annotations.
+ *   <li>{@link GeneratedComponent} - Registry of generated validation adapters.
+ *   <li>{@link MessageInterpolator} - Interpolates validation messages.
+ *   <li>{@link ValidatorCustomizer} - Allows customization of the validator instance.
+ * </ul>
+ */
 @Service
 public sealed interface ValidationExtension
     permits AdapterFactory,

validator/src/main/java/io/avaje/validation/spi/ValidatorCustomizer.java

@@ -1,12 +1,13 @@
 package io.avaje.validation.spi;
 
+import io.avaje.spi.ServiceProvider;
 import io.avaje.validation.Validator;
 
 /**
  * Callback interface that's used to customize a Validator.Builder.
  *
  * <p>These are service loaded when a Validator starts. The classes can be registered with {@link
- * BuilderCustomizer} or via a {@code provides} clause in module-info when using the java module
+ * ServiceProvider} or via a {@code provides} clause in module-info when using the java module
  * system.
  */
 @FunctionalInterface

validator/src/main/java/module-info.java

@@ -1,4 +1,33 @@
-/** Avaje Validation Library */
+/**
+ * Avaje Validation API - see {@link io.avaje.validation.Validator}.
+ *
+ * <h2>Example:</h2>
+ *
+ * <pre>{@code
+ * // Annotate classes with @Valid
+ *
+ * @Valid
+ * public class Address {
+ *
+ *   // annotate fields with constraints
+ *   @NotBlank
+ *   private String street;
+ *
+ *   @NotEmpty(message="must not be empty")
+ *   private List<@NotBlank String> owners; // message will be interpolated from bundle
+ *
+ *   //getters/setters
+ * }
+ *
+ * --------------------------------------------------
+ *
+ * final Validator validator = Validator.builder().build();
+ *
+ * Address address = ...;
+ * validator.validate(address);
+ *
+ * }</pre>
+ */
 module io.avaje.validation {
   exports io.avaje.validation;
   exports io.avaje.validation.adapter;