Builder methods should be generated via factories

core/src/main/java/org/javahelpers/simple/builders/core/annotations/SimpleBuilder.java

@@ -312,8 +312,8 @@
     OptionState generateAddToCollectionHelpers() default OptionState.UNSET;
 
     /**
-     * Generate unboxed optional methods that accept the inner type T directly instead of
-     * Optional&lt;T&gt;. <br>
+     * Generate unboxed optional methods that accept the inner type T directly instead of {@code
+     * Optional<T>}. <br>
      * For Optional fields, this generates a setter that accepts T and wraps it with
      * Optional.ofNullable().
      *
@@ -495,7 +495,7 @@
      * <p>Example:
      *
      * <pre>{@code
-     * @Generated("org.javahelpers.simple.builders.processor.BuilderProcessor")
+     * @Generated("Generated by org.javahelpers.simple.builders.processor.BuilderProcessor")
      * public class PersonDtoBuilder {
      *     // ...
      * }
@@ -542,6 +542,8 @@
      *
      * Default: ENABLED <br>
      * Compiler option: -Asimplebuilder.implementsBuilderBase
+     *
+     * @return the option state for implementing BuilderBase interface
      */
     OptionState implementsBuilderBase() default OptionState.UNSET;
 
@@ -565,6 +567,8 @@
      *
      * Default: ENABLED <br>
      * Compiler option: -Asimplebuilder.generateWithInterface
+     *
+     * @return the option state for generating With interface
      */
     OptionState generateWithInterface() default OptionState.UNSET;
 
@@ -586,6 +590,8 @@
      *
      * Default: DISABLED <br>
      * Compiler option: -Asimplebuilder.usingJacksonDeserializerAnnotation
+     *
+     * @return the option state for using Jackson deserializer annotation
      */
     OptionState usingJacksonDeserializerAnnotation() default OptionState.UNSET;
 
@@ -600,6 +606,8 @@
      *
      * <p>Default: DISABLED <br>
      * Compiler option: -Asimplebuilder.generateJacksonModule
+     *
+     * @return the option state for generating Jackson module
      */
     OptionState generateJacksonModule() default OptionState.UNSET;
 
@@ -614,6 +622,8 @@
      *
      * <p>Default: "" (empty - generate one module per package) <br>
      * Compiler option: -Asimplebuilder.jacksonModulePackage
+     *
+     * @return the package name for the Jackson module
      */
     String jacksonModulePackage() default "";
 
@@ -635,6 +645,8 @@
      *
      * Default: "Builder" <br>
      * Compiler option: -Asimplebuilder.builderSuffix
+     *
+     * @return the suffix for the builder class name
      */
     String builderSuffix() default "Builder";
 
@@ -661,6 +673,8 @@
      *
      * Default: "" (empty - no suffix) <br>
      * Compiler option: -Asimplebuilder.setterSuffix
+     *
+     * @return the suffix for setter method names
      */
     String setterSuffix() default "";
   }

docs/CONFIGURATION.md

@@ -16,6 +16,7 @@ Simple-builders supports fine-grained configuration through the `@SimpleBuilder.
   - [Conditional Logic](#conditional-logic)
   - [Access Control](#access-control)
   - [Collection Helpers](#collection-helpers)
+  - [Component Filtering](#component-filtering)
   - [Integration](#integration)
 - [Examples](#examples)
   - [Minimal Builder](#minimal-builder)
@@ -390,19 +391,26 @@ PersonDto person = PersonDtoBuilder.create()
 
 **Default**: `ENABLED` | **Compiler Option**: `-Asimplebuilder.generateStringFormatHelpers=ENABLED|DISABLED`
 
-Generates `String.format()` helper methods for String fields.
+Generates `String.format()` helper methods for String and Optional<String> fields.
 
 **When ENABLED**:
 ```java
-// Generated method
-public PersonDtoBuilder name(String format, Object... args) {
-    this.name = changedValue(String.format(format, args));
-    return this;
+// For String title field:
+public BookDtoBuilder title(String format, Object... args) {
+  this.title = changedValue(String.format(format, args));
+  return this;
+}
+
+// For Optional<String> subtitle field:
+public BookDtoBuilder subtitle(String format, Object... args) {
+  this.subtitle = changedValue(Optional.of(String.format(format, args)));
+  return this;
 }
 
 // Usage
-PersonDto person = PersonDtoBuilder.create()
-    .name("Hello, %s %s!", firstName, lastName)
+BookDto book = BookDtoBuilder.create()
+    .title("The %s Guide", "Complete")
+    .subtitle("A comprehensive %s tutorial for %s", "Java", "beginners")
     .build();
 ```
 
@@ -599,6 +607,34 @@ Generates methods using `HashMapBuilder` for fluent Map construction.
 
 ---
 
+### Component Filtering
+
+#### `deactivateGenerationComponents`
+
+**Default**: `""` (empty) | **Compiler Option**: `-Asimplebuilder.deactivateGenerationComponents=pattern1,pattern2,...`
+
+Deactivates specific method generators and builder enhancers by class name pattern. This allows you to override default generators/enhancers with your own custom implementations.
+
+**Primary Use Case**: Override Default Components
+
+When you want to replace a built-in generator or enhancer with your own custom implementation, you first deactivate the default component, then register your custom one via ServiceLoader.
+
+For detailed instructions on creating custom generators and enhancers, see [**CUSTOMIZING.md**](CUSTOMIZING.md).
+
+**Pattern Matching**:
+- **Exact match**: `ConditionalEnhancer` - deactivates exactly this class
+- **Wildcard suffix**: `*HelperGenerator` - deactivates all classes ending with HelperGenerator
+- **Wildcard prefix**: `String*` - deactivates all classes starting with String
+- **Wildcard anywhere**: `*Consumer*` - deactivates all classes containing Consumer
+
+**Feature Toggling vs Component Override**:
+- **Feature toggling**: Use `@SimpleBuilder.Options(generateConditionalHelper = DISABLED)`
+- **Component override**: Use `deactivateGenerationComponents` + custom ServiceLoader implementation
+
+See [**CUSTOMIZING.md**](CUSTOMIZING.md) for complete implementation examples and best practices.
+
+---
+
 ### Integration & Annotations
 
 #### `generateWithInterface`
@@ -1183,6 +1219,9 @@ methodAccess = AccessModifier.PRIVATE
 -Asimplebuilder.usingHashSetBuilderWithElementBuilders=ENABLED|DISABLED
 -Asimplebuilder.usingHashMapBuilder=ENABLED|DISABLED
 
+# Component Filtering
+-Asimplebuilder.deactivateGenerationComponents=pattern1,pattern2,...
+
 # Integration & Annotations
 -Asimplebuilder.generateWithInterface=ENABLED|DISABLED
 -Asimplebuilder.implementsBuilderBase=ENABLED|DISABLED