Enhance Javadoc documentation for TemplateStringFormatter and JavalidationModule

Author: RaniAgus

src/main/java/io/github/raniagus/javalidation/format/TemplateStringFormatter.java

@@ -1,9 +1,52 @@
 package io.github.raniagus.javalidation.format;
 
+/**
+ * Strategy interface for formatting {@link TemplateString} instances into plain strings.
+ * <p>
+ * This functional interface allows pluggable formatting strategies for error messages.
+ * Implementations typically use the template and arguments from {@link TemplateString} to
+ * produce a formatted output string, potentially considering locale, resource bundles, or
+ * other contextual information.
+ * <p>
+ * <b>Built-in implementations:</b>
+ * <ul>
+ *   <li>{@link MessageFormatTemplateStringFormatter} - Uses Java's {@link java.text.MessageFormat}</li>
+ *   <li>{@code MessageSourceTemplateStringFormatter} - Uses Spring's {@code MessageSource} for i18n</li>
+ * </ul>
+ * <p>
+ * <b>Usage example:</b>
+ * <pre>{@code
+ * TemplateStringFormatter formatter = TemplateStringFormatter.getDefault();
+ * TemplateString template = new TemplateString("Age must be at least {0}", new Object[]{18});
+ * String formatted = formatter.format(template); // "Age must be at least 18"
+ * }</pre>
+ * <p>
+ * Custom formatters can be registered with Jackson via {@link io.github.raniagus.javalidation.jackson.JavalidationModule}
+ * or Spring Boot auto-configuration properties.
+ *
+ * @see TemplateString
+ * @see MessageFormatTemplateStringFormatter
+ */
 @FunctionalInterface
 public interface TemplateStringFormatter {
+    /**
+     * Formats a template string into a plain string.
+     * <p>
+     * Implementations should use the {@link TemplateString#message()} as the template
+     * and {@link TemplateString#args()} as the placeholder arguments.
+     *
+     * @param templateString the template to format (must not be null)
+     * @return the formatted string (never null)
+     */
     String format(TemplateString templateString);
 
+    /**
+     * Returns the default formatter using {@link java.text.MessageFormat} syntax.
+     * <p>
+     * The default formatter supports placeholders like {@code {0}}, {@code {1}}, etc.
+     *
+     * @return a {@link MessageFormatTemplateStringFormatter} instance
+     */
     static TemplateStringFormatter getDefault() {
         return new MessageFormatTemplateStringFormatter();
     }

src/main/java/io/github/raniagus/javalidation/jackson/JavalidationModule.java

@@ -7,6 +7,41 @@
 import tools.jackson.databind.ValueSerializer;
 import tools.jackson.databind.module.SimpleModule;
 
+/**
+ * Jackson module for serializing javalidation types ({@link TemplateString} and {@link ValidationErrors}).
+ * <p>
+ * This module registers custom serializers to control how validation errors are serialized to JSON.
+ * By default, it uses:
+ * <ul>
+ *   <li>{@link TemplateStringSerializer} for {@link TemplateString} - formats templates using {@link TemplateStringFormatter}</li>
+ *   <li>{@link ValidationErrorsMixIn} for {@link ValidationErrors} - structures errors as {@code {root: [...], fields: {...}}}</li>
+ * </ul>
+ * <p>
+ * <b>Basic usage (default configuration):</b>
+ * <pre>{@code
+ * ObjectMapper mapper = JsonMapper.builder()
+ *     .addModule(JavalidationModule.getDefault())
+ *     .build();
+ * }</pre>
+ * <p>
+ * <b>Custom formatter (for internationalization):</b>
+ * <pre>{@code
+ * JavalidationModule module = JavalidationModule.builder()
+ *     .withTemplateStringFormatter(myCustomFormatter)
+ *     .build();
+ * }</pre>
+ * <p>
+ * <b>Flattened errors (flat array instead of nested structure):</b>
+ * <pre>{@code
+ * JavalidationModule module = JavalidationModule.builder()
+ *     .withFlattenedErrors()
+ *     .build();
+ * }</pre>
+ *
+ * @see TemplateStringSerializer
+ * @see FlattenedErrorsSerializer
+ * @see ValidationErrorsMixIn
+ */
 public class JavalidationModule extends SimpleModule {
     private final boolean useDefaultSerializer;
 
@@ -34,39 +69,115 @@ public void setupModule(SetupContext context) {
         }
     }
 
+    /**
+     * Returns a module instance with default serializers.
+     * <p>
+     * Equivalent to {@code JavalidationModule.builder().build()}.
+     *
+     * @return a new module with default configuration
+     */
     public static JavalidationModule getDefault() {
         return builder().build();
     }
 
+    /**
+     * Returns a new builder for customizing the module configuration.
+     *
+     * @return a new {@link Builder} instance
+     */
     public static Builder builder() {
         return new Builder();
     }
 
+    /**
+     * Builder for configuring {@link JavalidationModule} with custom serializers.
+     * <p>
+     * Use this builder to customize how {@link TemplateString} and {@link ValidationErrors}
+     * are serialized to JSON.
+     *
+     * @see #withTemplateStringFormatter(TemplateStringFormatter)
+     * @see #withFlattenedErrors()
+     */
     public static class Builder {
         private ValueSerializer<TemplateString> templateStringSerializer = new TemplateStringSerializer();
         private @Nullable ValueSerializer<ValidationErrors> validationErrorsSerializer;
 
+        /**
+         * Creates a new builder with default serializers.
+         */
         public Builder() {
         }
 
+        /**
+         * Configures a custom formatter for {@link TemplateString} serialization.
+         * <p>
+         * This is a convenience method that wraps the formatter in a {@link TemplateStringSerializer}.
+         * Use this to customize how template messages are formatted (e.g., for i18n).
+         * <p>
+         * Example:
+         * <pre>{@code
+         * builder.withTemplateStringFormatter(new MessageSourceTemplateStringFormatter(messageSource, locale))
+         * }</pre>
+         *
+         * @param formatter the formatter to use (must not be null)
+         * @return this builder for method chaining
+         * @see #withTemplateStringSerializer(ValueSerializer)
+         */
         public Builder withTemplateStringFormatter(TemplateStringFormatter formatter) {
             return withTemplateStringSerializer(new TemplateStringSerializer(formatter));
         }
 
+        /**
+         * Configures the module to serialize {@link ValidationErrors} as a flat array of error strings.
+         * <p>
+         * By default, errors are serialized with nested structure: {@code {root: [...], fields: {...}}}.
+         * This method changes the serialization to a simple flat array: {@code ["error1", "error2", ...]}.
+         * <p>
+         * Example output:
+         * <pre>{@code
+         * ["Name is required", "Age must be positive"]
+         * }</pre>
+         *
+         * @return this builder for method chaining
+         * @see FlattenedErrorsSerializer
+         */
         public Builder withFlattenedErrors() {
             return withValidationErrorsSerializer(new FlattenedErrorsSerializer());
         }
 
+        /**
+         * Configures a custom serializer for {@link TemplateString}.
+         * <p>
+         * Use this for full control over template serialization. For most use cases,
+         * {@link #withTemplateStringFormatter(TemplateStringFormatter)} is simpler.
+         *
+         * @param templateStringSerializer the custom serializer (must not be null)
+         * @return this builder for method chaining
+         */
         public Builder withTemplateStringSerializer(ValueSerializer<TemplateString> templateStringSerializer) {
             this.templateStringSerializer = templateStringSerializer;
             return this;
         }
 
+        /**
+         * Configures a custom serializer for {@link ValidationErrors}.
+         * <p>
+         * Use this for full control over error structure serialization. For flattened output,
+         * {@link #withFlattenedErrors()} is simpler.
+         *
+         * @param validationErrorsSerializer the custom serializer (must not be null)
+         * @return this builder for method chaining
+         */
         public Builder withValidationErrorsSerializer(ValueSerializer<ValidationErrors> validationErrorsSerializer) {
             this.validationErrorsSerializer = validationErrorsSerializer;
             return this;
         }
 
+        /**
+         * Builds the configured {@link JavalidationModule}.
+         *
+         * @return a new module instance with the configured serializers
+         */
         public JavalidationModule build() {
             return new JavalidationModule(templateStringSerializer, validationErrorsSerializer);
         }