Generate JavaDoc usage examples in builders + processor model refactor

README.md

@@ -69,6 +69,7 @@ Value semantics (`equals`, `hashCode`, `toString`) and generating brand-new immu
 - **Annotation Preservation**: Validation annotations are automatically copied to builder methods
 - **With Interface Pattern**: Type-safe object modifications using generated With interfaces
 - **Jackson Support**: Supporting Jackson deserialization via `@JsonPOJOBuilder` and optional generation of `SimpleModule`s (one per package) (both need to be enabled)
+- **JavaDoc Usage Examples**: Generated builder methods include auto-generated usage examples in their JavaDoc (per-method fluent snippets plus a class-level example), so IDE tooltips show exactly how to use each builder
 
 ## Requirements
 

example-custom-generator/src/main/java/org/javahelpers/simple/builders/example/custom/StringValidationGenerator.java

@@ -27,7 +27,7 @@
 import java.util.List;
 import org.apache.commons.lang3.StringUtils;
 import org.javahelpers.simple.builders.processor.model.core.FieldDto;
-import org.javahelpers.simple.builders.processor.model.method.MethodDto;
+import org.javahelpers.simple.builders.processor.model.method.BuilderMethodDto;
 import org.javahelpers.simple.builders.processor.model.type.TypeName;
 import org.javahelpers.simple.builders.processor.model.javadoc.JavadocDto;
 import org.javahelpers.simple.builders.processor.generators.MethodGenerator;
@@ -66,7 +66,7 @@ public boolean appliesTo(FieldDto field, TypeName dtoType, ProcessingContext con
     }
 
     @Override
-    public List<MethodDto> generateMethods(FieldDto field, TypeName builderType, ProcessingContext context) {
+    public List<BuilderMethodDto> generateMethods(FieldDto field, TypeName builderType, ProcessingContext context) {
         String fieldInDto = field.getOriginalFieldName();
         String fieldInBuilder = field.getFieldNameInBuilder();
         String methodName = "validate" + StringUtils.capitalize(fieldInDto);
@@ -79,7 +79,7 @@ public List<MethodDto> generateMethods(FieldDto field, TypeName builderType, Pro
             fieldInBuilder, fieldInBuilder, StringUtils.capitalize(fieldInDto)
         );
 
-        MethodDto validationMethod = new MethodDto(methodName, builderType);
+        BuilderMethodDto validationMethod = new BuilderMethodDto(methodName, builderType);
         validationMethod.setCode(methodBody);
         validationMethod.setJavadoc(
             new JavadocDto("Validates that the " + fieldInDto + " field is not null or empty.")

example/generated-example-builder/org/javahelpers/simple/builders/example/BookDtoBuilder.java

@@ -20,6 +20,30 @@
  * This builder provides a fluent API for creating instances of org.javahelpers.simple.builders.example.BookDto with
  * method chaining and validation. Use the static {@code create()} method to obtain a new builder instance, configure
  * the desired properties using the setter methods, and then call {@code build()} to create the final DTO.
+ * 
+ * <h4>Example:</h4>
+ * 
+ * <pre>{@code
+ * BookDto result = BookDtoBuilder.create()
+ *     .author("example value")
+ *     .available(true)
+ *     .category('x')
+ *     .discount(3.14f)
+ *     .exactPrice(BigDecimal.valueOf(3.14))
+ *     .genres(Set.of("example value"))
+ *     .isbn("example value")
+ *     .lastUpdated(LocalDateTime.now())
+ *     .metadata(Map.of("example value", "example value"))
+ *     .pages(42)
+ *     .price(3.14)
+ *     .publishDate(LocalDate.now())
+ *     .publisher(PersonDtoBuilder.create().build())
+ *     .salesCount(42L)
+ *     .subtitle(Optional.of("example value"))
+ *     .tags(List.of("example value"))
+ *     .title("example value")
+ *     .build();
+ * }</pre>
  */
 public class BookDtoBuilder {
 
@@ -136,6 +160,12 @@ public BookDtoBuilder(BookDto instance) {
   /**
    * Creating a new builder for {@code org.javahelpers.simple.builders.example.BookDto}.
    * 
+   * <h4>Example:</h4>
+   * 
+   * <pre>{@code
+   * BookDtoBuilder builder = BookDtoBuilder.create();
+   * }</pre>
+   * 
    * @return builder for {@code org.javahelpers.simple.builders.example.BookDto}
    */
   public static BookDtoBuilder create() {
@@ -144,6 +174,14 @@ public static BookDtoBuilder create() {
 
   /**
    * Sets the value for <code>author</code>.
+   * <p>
+   * Generated from setter {@link BookDto#setAuthor(String) setAuthor(String author)}
+   * 
+   * <h4>Example:</h4>
+   * 
+   * <pre>{@code
+   * builder.author("example value");
+   * }</pre>
    * 
    * @param author the book author to set
    * @return current instance of builder
@@ -155,6 +193,14 @@ public BookDtoBuilder author(String author) {
 
   /**
    * Sets the value for <code>available</code>.
+   * <p>
+   * Generated from setter {@link BookDto#setAvailable(boolean) setAvailable(boolean available)}
+   * 
+   * <h4>Example:</h4>
+   * 
+   * <pre>{@code
+   * builder.available(true);
+   * }</pre>
    * 
    * @param available true if available, false otherwise
    * @return current instance of builder
@@ -166,6 +212,14 @@ public BookDtoBuilder available(boolean available) {
 
   /**
    * Sets the value for <code>category</code>.
+   * <p>
+   * Generated from setter {@link BookDto#setCategory(char) setCategory(char category)}
+   * 
+   * <h4>Example:</h4>
+   * 
+   * <pre>{@code
+   * builder.category('x');
+   * }</pre>
    * 
    * @param category the category code to set
    * @return current instance of builder
@@ -177,6 +231,14 @@ public BookDtoBuilder category(char category) {
 
   /**
    * Sets the value for <code>discount</code>.
+   * <p>
+   * Generated from setter {@link BookDto#setDiscount(float) setDiscount(float discount)}
+   * 
+   * <h4>Example:</h4>
+   * 
+   * <pre>{@code
+   * builder.discount(3.14f);
+   * }</pre>
    * 
    * @param discount the discount percentage to set
    * @return current instance of builder
@@ -188,6 +250,8 @@ public BookDtoBuilder discount(float discount) {
 
   /**
    * Sets the value for <code>edition</code>.
+   * <p>
+   * Generated from setter {@link BookDto#setEdition(short) setEdition(short edition)}
    * 
    * @param edition the edition number to set
    * @return current instance of builder
@@ -199,6 +263,14 @@ public BookDtoBuilder edition(short edition) {
 
   /**
    * Sets the value for <code>exactPrice</code>.
+   * <p>
+   * Generated from setter {@link BookDto#setExactPrice(BigDecimal) setExactPrice(BigDecimal exactPrice)}
+   * 
+   * <h4>Example:</h4>
+   * 
+   * <pre>{@code
+   * builder.exactPrice(BigDecimal.valueOf(3.14));
+   * }</pre>
    * 
    * @param exactPrice the exact book price to set
    * @return current instance of builder
@@ -210,6 +282,14 @@ public BookDtoBuilder exactPrice(BigDecimal exactPrice) {
 
   /**
    * Sets the value for <code>genres</code>.
+   * <p>
+   * Generated from setter {@link BookDto#setGenres(Set) setGenres(Set<String> genres)}
+   * 
+   * <h4>Example:</h4>
+   * 
+   * <pre>{@code
+   * builder.genres(Set.of("example value"));
+   * }</pre>
    * 
    * @param genres the set of genres to set
    * @return current instance of builder
@@ -221,6 +301,14 @@ public BookDtoBuilder genres(Set<String> genres) {
 
   /**
    * Sets the value for <code>isbn</code>.
+   * <p>
+   * Generated from setter {@link BookDto#setIsbn(String) setIsbn(String isbn)}
+   * 
+   * <h4>Example:</h4>
+   * 
+   * <pre>{@code
+   * builder.isbn("example value");
+   * }</pre>
    * 
    * @param isbn the ISBN to set
    * @return current instance of builder
@@ -232,6 +320,14 @@ public BookDtoBuilder isbn(String isbn) {
 
   /**
    * Sets the value for <code>lastUpdated</code>.
+   * <p>
+   * Generated from setter {@link BookDto#setLastUpdated(LocalDateTime) setLastUpdated(LocalDateTime lastUpdated)}
+   * 
+   * <h4>Example:</h4>
+   * 
+   * <pre>{@code
+   * builder.lastUpdated(LocalDateTime.now());
+   * }</pre>
    * 
    * @param lastUpdated the last update timestamp to set
    * @return current instance of builder
@@ -243,6 +339,14 @@ public BookDtoBuilder lastUpdated(LocalDateTime lastUpdated) {
 
   /**
    * Sets the value for <code>metadata</code>.
+   * <p>
+   * Generated from setter {@link BookDto#setMetadata(Map) setMetadata(Map<String, String> metadata)}
+   * 
+   * <h4>Example:</h4>
+   * 
+   * <pre>{@code
+   * builder.metadata(Map.of("example value", "example value"));
+   * }</pre>
    * 
    * @param metadata the metadata map to set
    * @return current instance of builder
@@ -254,6 +358,14 @@ public BookDtoBuilder metadata(Map<String, String> metadata) {
 
   /**
    * Sets the value for <code>pages</code>.
+   * <p>
+   * Generated from setter {@link BookDto#setPages(int) setPages(int pages)}
+   * 
+   * <h4>Example:</h4>
+   * 
+   * <pre>{@code
+   * builder.pages(42);
+   * }</pre>
    * 
    * @param pages the page count to set
    * @return current instance of builder
@@ -265,6 +377,14 @@ public BookDtoBuilder pages(int pages) {
 
   /**
    * Sets the value for <code>price</code>.
+   * <p>
+   * Generated from setter {@link BookDto#setPrice(double) setPrice(double price)}
+   * 
+   * <h4>Example:</h4>
+   * 
+   * <pre>{@code
+   * builder.price(3.14);
+   * }</pre>
    * 
    * @param price the book price to set
    * @return current instance of builder
@@ -276,6 +396,14 @@ public BookDtoBuilder price(double price) {
 
   /**
    * Sets the value for <code>publishDate</code>.
+   * <p>
+   * Generated from setter {@link BookDto#setPublishDate(LocalDate) setPublishDate(LocalDate publishDate)}
+   * 
+   * <h4>Example:</h4>
+   * 
+   * <pre>{@code
+   * builder.publishDate(LocalDate.now());
+   * }</pre>
    * 
    * @param publishDate the publication date to set
    * @return current instance of builder
@@ -287,6 +415,14 @@ public BookDtoBuilder publishDate(LocalDate publishDate) {
 
   /**
    * Sets the value for <code>publisher</code>.
+   * <p>
+   * Generated from setter {@link BookDto#setPublisher(PersonDto) setPublisher(PersonDto publisher)}
+   * 
+   * <h4>Example:</h4>
+   * 
+   * <pre>{@code
+   * builder.publisher(PersonDtoBuilder.create().build());
+   * }</pre>
    * 
    * @param publisher the publisher to set
    * @return current instance of builder
@@ -298,6 +434,8 @@ public BookDtoBuilder publisher(PersonDto publisher) {
 
   /**
    * Sets the value for <code>rating</code>.
+   * <p>
+   * Generated from setter {@link BookDto#setRating(byte) setRating(byte rating)}
    * 
    * @param rating the book rating to set
    * @return current instance of builder
@@ -309,6 +447,14 @@ public BookDtoBuilder rating(byte rating) {
 
   /**
    * Sets the value for <code>salesCount</code>.
+   * <p>
+   * Generated from setter {@link BookDto#setSalesCount(long) setSalesCount(long salesCount)}
+   * 
+   * <h4>Example:</h4>
+   * 
+   * <pre>{@code
+   * builder.salesCount(42L);
+   * }</pre>
    * 
    * @param salesCount the sales count to set
    * @return current instance of builder
@@ -320,6 +466,14 @@ public BookDtoBuilder salesCount(long salesCount) {
 
   /**
    * Sets the value for <code>subtitle</code>.
+   * <p>
+   * Generated from setter {@link BookDto#setSubtitle(Optional) setSubtitle(Optional<String> subtitle)}
+   * 
+   * <h4>Example:</h4>
+   * 
+   * <pre>{@code
+   * builder.subtitle(Optional.of("example value"));
+   * }</pre>
    * 
    * @param subtitle an Optional containing the subtitle to set
    * @return current instance of builder
@@ -331,6 +485,14 @@ public BookDtoBuilder subtitle(Optional<String> subtitle) {
 
   /**
    * Sets the value for <code>tags</code>.
+   * <p>
+   * Generated from setter {@link BookDto#setTags(List) setTags(List<String> tags)}
+   * 
+   * <h4>Example:</h4>
+   * 
+   * <pre>{@code
+   * builder.tags(List.of("example value"));
+   * }</pre>
    * 
    * @param tags the list of tags to set
    * @return current instance of builder
@@ -342,6 +504,14 @@ public BookDtoBuilder tags(List<String> tags) {
 
   /**
    * Sets the value for <code>title</code>.
+   * <p>
+   * Generated from setter {@link BookDto#setTitle(String) setTitle(String title)}
+   * 
+   * <h4>Example:</h4>
+   * 
+   * <pre>{@code
+   * builder.title("example value");
+   * }</pre>
    * 
    * @param title the book title to set
    * @return current instance of builder
@@ -353,6 +523,8 @@ public BookDtoBuilder title(String title) {
 
   /**
    * Validates that the author field is not null or empty.
+   * <p>
+   * Generated from setter {@link BookDto#setAuthor(String) setAuthor(String author)}
    * 
    * @return this builder instance for chaining
    * @throws IllegalArgumentException if author is null or empty
@@ -366,6 +538,8 @@ BookDtoBuilder validateAuthor() {
 
   /**
    * Validates that the isbn field is not null or empty.
+   * <p>
+   * Generated from setter {@link BookDto#setIsbn(String) setIsbn(String isbn)}
    * 
    * @return this builder instance for chaining
    * @throws IllegalArgumentException if isbn is null or empty
@@ -379,6 +553,8 @@ BookDtoBuilder validateIsbn() {
 
   /**
    * Validates that the title field is not null or empty.
+   * <p>
+   * Generated from setter {@link BookDto#setTitle(String) setTitle(String title)}
    * 
    * @return this builder instance for chaining
    * @throws IllegalArgumentException if title is null or empty
@@ -392,6 +568,12 @@ BookDtoBuilder validateTitle() {
 
   /**
    * Builds the configured DTO instance.
+   * 
+   * <h4>Example:</h4>
+   * 
+   * <pre>{@code
+   * BookDto result = builder.build();
+   * }</pre>
    */
   public BookDto build() {
     if (this.available.isSet() && this.available.value() == null) {