issue-1384: Fluent API - Add JavaDoc to core workflow builders [TIER 1] by domhanak · Pull Request #1385 · serverlessworkflow/sdk-java

domhanak · 2026-05-12T14:00:44Z

Many thanks for submitting your Pull Request ❤️!

What this PR does / why we need it:
This PR is initial draft of the JavaDoc implementation proposed in #1384

Special notes for reviewers:

This is a result of analysis using IBM Bob, I am creating this draft PR to gather feedback and also have better view on the result ( I prefer reviewing here in GH )

Additional information (if needed):

Bob analyzed we have 4 TIERS ( we should prioritize - 1 highest, 4 lowest )
Each tier is split into smaller unit and this is a result of Bob solving first part of TIER 1
TIER 1 JavaDoc improvements - Unit 1.1: Fluent API Core Workflow Builders <- This PR

Pending, will continue if we deem the result good:
TIER 1 JavaDoc improvements - Unit 1.2: Fluent API Call & Communication Tasks
TIER 1 JavaDoc improvements - Unit 1.3: Fluent API Event Handling
TIER 1 JavaDoc improvements - Unit 1.4: Fluent API Error Handling & Control Flow
TIER 1 JavaDoc improvements - Unit 1.5: Core Runtime Application & Definition
TIER 1 JavaDoc improvements - Unit 1.6: Core Runtime Instance & Execution
TIER 1 JavaDoc improvements - Unit 1.7: Annotations

Guidelines applied when generating the docs:

✅ Class-level JavaDoc with:

Brief one-line descriptions
Detailed explanations of purpose and usage
Complete usage examples (2-4 per class)
Links to related classes using @see tags
Thread-safety notes
@since tags (1.0.0)
✅ Method-level JavaDoc with:

Clear descriptions using present tense
@param tags for all parameters
@return tags for builder methods
Usage examples for complex methods
@see references to related methods
✅ Builder Pattern Documentation:

Method chaining explained
Builder lifecycle clarified
Complete builder usage examples
Immutability/mutability notes
✅ Style Guidelines:

Present tense throughout
Concise but complete descriptions
Code examples in {@code} and <pre>{@code}</pre> blocks
Proper HTML tags in JavaDoc
Consistent formatting across all files
No code logic changes - only JavaDoc additions```

Signed-off-by: Dominik Hanak <dhanak@redhat.com>

fjtirado · 2026-06-12T11:59:21Z

@domhanak Is this one ready for review? (Im asking because the PR is a draft)

fjtirado · 2026-06-22T09:52:05Z

@ricardozanini @matheusandre1 I think that one is good (AI javadoc generation is pretty neat), do you mind reviewing?

Copilot

Pull request overview

This PR is an initial draft of the TIER 1 / Unit 1.1 JavaDoc improvements for the fluent API core workflow builders, adding class- and method-level JavaDoc (including usage examples) without changing runtime logic.

Changes:

Added extensive class-level and method-level JavaDoc to the fluent workflow/task builders.
Added usage examples and cross-references (@see) for key builder entry points and task builders.
Documented builder lifecycle and thread-safety expectations across the core fluent builders.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 12 comments.

Show a summary per file

File	Description
fluent/spec/src/main/java/io/serverlessworkflow/fluent/spec/WorkflowBuilder.java	Adds class/method JavaDoc and a primary workflow construction example.
fluent/spec/src/main/java/io/serverlessworkflow/fluent/spec/DoTaskBuilder.java	Adds class/method JavaDoc for the main sequential task-composition builder and its task methods.
fluent/spec/src/main/java/io/serverlessworkflow/fluent/spec/SetTaskBuilder.java	Adds JavaDoc describing variable assignment semantics (expr vs put) and examples.
fluent/spec/src/main/java/io/serverlessworkflow/fluent/spec/SwitchTaskBuilder.java	Adds JavaDoc for conditional branching builder behavior, examples, and build semantics.
fluent/spec/src/main/java/io/serverlessworkflow/fluent/spec/ForkTaskBuilder.java	Adds JavaDoc for parallel branch composition builder and internal builder creation hooks.
fluent/spec/src/main/java/io/serverlessworkflow/fluent/spec/ForEachTaskBuilder.java	Adds JavaDoc for iteration builder configuration and build semantics.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

+ *     .tasks(tasks -> tasks
+ *         .set(set -> set
+ *             .name("validate-order")
+ *             .set("isValid", "${ .order.total > 0 }"))
+ *         .switchTask(sw -> sw
+ *             .name("check-validation")
+ *             .switchItem(item -> item
+ *                 .when("${ .isValid }")
+ *                 .then("process-order"))
+ *             .switchItem(item -> item
+ *                 .when("${ !.isValid }")
+ *                 .then("reject-order"))))


+ * DoTaskBuilder tasks = new DoTaskBuilder(0)
+ *     .set("initialize", set -> set
+ *         .set("counter", "0")
+ *         .set("status", "started"))
+ *     .http("fetch-data", http -> http
+ *         .call(call -> call
+ *             .with(endpoint -> endpoint
+ *                 .uri("https://api.example.com/data"))
+ *             .method("GET")))
+ *     .switchCase("process-result", sw -> sw
+ *         .switchItem(item -> item
+ *             .when("${ .response.status == 200 }")
+ *             .then("success-handler"))
+ *         .switchItem(item -> item
+ *             .when("${ .response.status >= 400 }")
+ *             .then("error-handler")))
+ *     .emit("notify", emit -> emit
+ *         .event(event -> event
+ *             .with(props -> props
+ *                 .type("workflow.completed")
+ *                 .source("workflow-engine"))));


+   * builder.forEach("process-items", forEach -> forEach
+   *     .for_("item")
+   *     .in("${ .items }")
+   *     .do_(tasks -> tasks
+   *         .http("process-item", http -> http


+   * <p>Creates a task that executes multiple branches concurrently. Supports different
+   * competition modes (wait for all, wait for first, wait for N) and branch configuration.
+   *
+   * <p><strong>Example:</strong>
+   * <pre>{@code
+   * builder.fork("parallel-processing", fork -> fork
+   *     .compete(CompetitionMode.ALL_OF)


+   * builder.set("calculate-total", set -> set
+   *     .set("subtotal", "${ .items | map(.price) | add }")
+   *     .set("tax", "${ .subtotal * 0.1 }")
+   *     .set("total", "${ .subtotal + .tax }"));


+ * SwitchTaskBuilder builder = new SwitchTaskBuilder()
+ *     .on("small-order", switchCase -> switchCase
+ *         .when("${ .total < 100 }")
+ *         .then("small-order-handler"))
+ *     .on("medium-order", switchCase -> switchCase
+ *         .when("${ .total >= 100 and .total < 1000 }")
+ *         .then("medium-order-handler"))
+ *     .on("large-order", switchCase -> switchCase
+ *         .when("${ .total >= 1000 }")
+ *         .then("large-order-handler"));


+  /**
+   * Builds and returns the configured SwitchTask.
+   *
+   * <p>This method finalizes the task configuration and creates the immutable SwitchTask
+   * instance with all defined switch cases. The cases will be evaluated in the order they
+   * were added to the builder.
+   *
+   * <p><strong>Note:</strong> After calling this method, the builder should not be reused.
+   * Create a new builder instance for additional tasks.
+   *
+   * @return the configured SwitchTask ready for execution
+   */


+   * <p>The value can be:
+   * <ul>
+   *   <li>A literal value (string, number, boolean, null)</li>
+   *   <li>An expression string starting with {@code ${ } for dynamic evaluation</li>


+  /**
+   * Builds and returns the configured SetTask.
+   *
+   * <p>This method finalizes the task configuration and creates the immutable SetTask instance.
+   * If no expression was set via {@link #expr(String)}, the accumulated key-value pairs from
+   * {@link #put(String, Object)} calls are used.
+   *
+   * <p><strong>Note:</strong> After calling this method, the builder should not be reused.
+   * Create a new builder instance for additional tasks.
+   *
+   * @return the configured SetTask ready for execution
+   */


+  /**
+   * Builds and returns the configured ForTask.
+   *
+   * <p>This method finalizes the task configuration and creates the immutable ForTask
+   * instance with all iteration settings and nested tasks.
+   *
+   * <p><strong>Note:</strong> After calling this method, the builder should not be reused.
+   * Create a new builder instance for additional tasks.
+   *
+   * @return the configured ForTask ready for execution
+   */


fjtirado · 2026-06-22T11:40:05Z

@domhanak There is a curious AI fight here, please take a look and fix according to human criteria ;)

ricardozanini

Guys, unfortunately, I don't have time to go through this, but my rules of thumb:

Consider the co-pilot's comment, it knows a lot about our code base
Don't over-document private/protected methods
Make sure that the docs bind to existing code

Many thanks for this, looks really useful.

ricardozanini · 2026-06-22T14:48:54Z

+   *
+   * @return this DoTaskBuilder instance
+   */
  @Override


I don't think we need obvious javadoc, which just pollutes the API. Add a rule to Bob to avoid doing this. Also, this is a protected-visible method; it's not part of the user-facing API.

issue-1384: Fluent API - Add JavaDoc to core workflow builders

bac92c2

Signed-off-by: Dominik Hanak <dhanak@redhat.com>

domhanak force-pushed the issue-1384 branch from 63a023c to bac92c2 Compare May 12, 2026 14:02

fjtirado approved these changes Jun 22, 2026

View reviewed changes

fjtirado marked this pull request as ready for review June 22, 2026 09:51

Copilot AI review requested due to automatic review settings June 22, 2026 09:51

Copilot started reviewing on behalf of fjtirado June 22, 2026 09:52 View session

Copilot AI reviewed Jun 22, 2026

View reviewed changes

ricardozanini reviewed Jun 22, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

issue-1384: Fluent API - Add JavaDoc to core workflow builders [TIER 1]#1385

issue-1384: Fluent API - Add JavaDoc to core workflow builders [TIER 1]#1385
domhanak wants to merge 1 commit into
serverlessworkflow:mainfrom
domhanak:issue-1384

domhanak commented May 12, 2026

Uh oh!

fjtirado commented Jun 12, 2026

Uh oh!

fjtirado commented Jun 22, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

fjtirado commented Jun 22, 2026

Uh oh!

ricardozanini left a comment

Uh oh!

ricardozanini Jun 22, 2026

Uh oh!

fjtirado Jun 22, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

domhanak commented May 12, 2026

Uh oh!

fjtirado commented Jun 12, 2026

Uh oh!

fjtirado commented Jun 22, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

fjtirado commented Jun 22, 2026

Uh oh!

ricardozanini left a comment

Choose a reason for hiding this comment

Uh oh!

ricardozanini Jun 22, 2026

Choose a reason for hiding this comment

Uh oh!

fjtirado Jun 22, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants