improve javadocs

Co-authored-by: Copilot <copilot@github.com>

Author: devhawk

transact/src/main/java/dev/dbos/transact/StartWorkflowOptions.java

@@ -14,23 +14,34 @@
 import org.jspecify.annotations.Nullable;
 
 /**
- * Options for starting a workflow, including: Assigning the workflow idempotency ID Enqueuing, with
- * options Setting a timeout.
+ * Options for starting a workflow instance.
+ *
+ * <p>This record encapsulates configuration for workflow execution, including:
+ *
+ * <ul>
+ *   <li>Idempotency and tracking via a unique workflow ID
+ *   <li>Timeout and deadline management
+ *   <li>Queue assignment, deduplication, priority, and partitioning
+ *   <li>Optional execution delay and application version targeting
+ * </ul>
  *
  * @param workflowId The unique identifier for the workflow instance. Used for idempotency and
- *     tracking.
+ *     tracking. May be null.
  * @param timeout The timeout configuration specifying how long the workflow may run before
- *     expiring; this is promoted to a deadline at execution time.
+ *     expiring. Promoted to a deadline at execution time. May be null.
  * @param deadline The absolute time by which the workflow must start or complete before being
- *     canceled, if timeout is also set the deadline is derived from the timeout.
- * @param queueName An optional name of the queue to which the workflow should be enqueued for
- *     execution.
- * @param deduplicationId If `queueName` is specified, an optional ID used to prevent duplicate
- *     enqueued workflows.
- * @param priority If `queueName` is specified and refers to a queue with priority enabled, the
- *     priority to assign.
- * @param queuePartitionKey If `queueName` is specified, an optional partition key used to
- *     distribute workflows across queue partitions for load balancing and ordered processing.
+ *     canceled. If both timeout and deadline are set, the earlier is used. May be null.
+ * @param queueName Optional name of the queue to which the workflow should be enqueued for
+ *     execution. May be null.
+ * @param deduplicationId If {@code queueName} is specified, an optional ID used to prevent
+ *     duplicate enqueued workflows. May be null.
+ * @param priority If {@code queueName} is specified and refers to a queue with priority enabled,
+ *     the priority to assign. May be null.
+ * @param queuePartitionKey If {@code queueName} is specified, an optional partition key used to
+ *     distribute workflows across queue partitions for load balancing and ordered processing. May
+ *     be null.
+ * @param delay Optional delay before the workflow starts executing. May be null.
+ * @param appVersion Optional application version to target for workflow execution. May be null.
  */
 public record StartWorkflowOptions(
     @Nullable String workflowId,
@@ -73,22 +84,35 @@ public record StartWorkflowOptions(
     }
   }
 
-  /** Construct with default options */
+  /** Construct with default options (all fields null). */
   public StartWorkflowOptions() {
     this(null, null, null, null, null, null, null, null, null);
   }
 
-  /** Construct with a specified workflow ID */
+  /**
+   * Construct with a specified workflow ID.
+   *
+   * @param workflowId the workflow ID to assign
+   */
   public StartWorkflowOptions(String workflowId) {
     this(workflowId, null, null, null, null, null, null, null, null);
   }
 
-  /** Construct with a specified queue */
+  /**
+   * Construct with a specified queue.
+   *
+   * @param queue the queue to assign the workflow to
+   */
   public StartWorkflowOptions(@NonNull Queue queue) {
     this(null, null, null, queue.name(), null, null, null, null, null);
   }
 
-  /** Produces a new StartWorkflowOptions that overrides the ID assigned to the started workflow */
+  /**
+   * Returns a new StartWorkflowOptions with the specified workflow ID.
+   *
+   * @param workflowId the workflow ID to assign
+   * @return a new StartWorkflowOptions with the updated workflow ID
+   */
   public @NonNull StartWorkflowOptions withWorkflowId(@Nullable String workflowId) {
     return new StartWorkflowOptions(
         workflowId,
@@ -102,7 +126,12 @@ public StartWorkflowOptions(@NonNull Queue queue) {
         this.appVersion);
   }
 
-  /** Produces a new StartWorkflowOptions that overrides timeout value for the started workflow */
+  /**
+   * Returns a new StartWorkflowOptions with the specified timeout.
+   *
+   * @param timeout the timeout to assign
+   * @return a new StartWorkflowOptions with the updated timeout
+   */
   public @NonNull StartWorkflowOptions withTimeout(@Nullable Timeout timeout) {
     return new StartWorkflowOptions(
         this.workflowId,
@@ -116,22 +145,42 @@ public StartWorkflowOptions(@NonNull Queue queue) {
         this.appVersion);
   }
 
-  /** Produces a new StartWorkflowOptions that overrides timeout value for the started workflow */
+  /**
+   * Returns a new StartWorkflowOptions with the specified timeout duration.
+   *
+   * @param timeout the timeout duration to assign
+   * @return a new StartWorkflowOptions with the updated timeout
+   */
   public @NonNull StartWorkflowOptions withTimeout(@NonNull Duration timeout) {
     return withTimeout(Timeout.of(timeout));
   }
 
-  /** Produces a new StartWorkflowOptions that overrides timeout value for the started workflow */
+  /**
+   * Returns a new StartWorkflowOptions with the specified timeout value and unit.
+   *
+   * @param value the timeout value
+   * @param unit the time unit for the timeout
+   * @return a new StartWorkflowOptions with the updated timeout
+   */
   public @NonNull StartWorkflowOptions withTimeout(long value, @NonNull TimeUnit unit) {
     return withTimeout(Duration.ofNanos(unit.toNanos(value)));
   }
 
-  /** Produces a new StartWorkflowOptions that removes the timeout behavior */
+  /**
+   * Returns a new StartWorkflowOptions with no timeout (disables timeout behavior).
+   *
+   * @return a new StartWorkflowOptions with timeout disabled
+   */
   public @NonNull StartWorkflowOptions withNoTimeout() {
     return withTimeout(Timeout.none());
   }
 
-  /** Produces a new StartWorkflowOptions that overrides deadline value for the started workflow */
+  /**
+   * Returns a new StartWorkflowOptions with the specified deadline.
+   *
+   * @param deadline the absolute deadline to assign
+   * @return a new StartWorkflowOptions with the updated deadline
+   */
   public @NonNull StartWorkflowOptions withDeadline(@Nullable Instant deadline) {
     return new StartWorkflowOptions(
         this.workflowId,
@@ -145,7 +194,12 @@ public StartWorkflowOptions(@NonNull Queue queue) {
         this.appVersion);
   }
 
-  /** Produces a new StartWorkflowOptions that assigns the started workflow to a queue */
+  /**
+   * Returns a new StartWorkflowOptions with the specified queue name.
+   *
+   * @param queue the queue name to assign
+   * @return a new StartWorkflowOptions with the updated queue name
+   */
   public @NonNull StartWorkflowOptions withQueue(@Nullable String queue) {
     return new StartWorkflowOptions(
         this.workflowId,
@@ -159,14 +213,22 @@ public StartWorkflowOptions(@NonNull Queue queue) {
         this.appVersion);
   }
 
-  /** Produces a new StartWorkflowOptions that assigns the started workflow to a queue */
+  /**
+   * Returns a new StartWorkflowOptions with the specified queue.
+   *
+   * @param queue the queue to assign
+   * @return a new StartWorkflowOptions with the updated queue name
+   */
   public @NonNull StartWorkflowOptions withQueue(@NonNull Queue queue) {
     return withQueue(queue.name());
   }
 
   /**
-   * Produces a new StartWorkflowOptions that assigns a queue deduplication ID. Note that the queue
-   * must also be specified.
+   * Returns a new StartWorkflowOptions with the specified queue deduplication ID. Note: The queue
+   * must also be specified for deduplication to take effect.
+   *
+   * @param deduplicationId the deduplication ID to assign
+   * @return a new StartWorkflowOptions with the updated deduplication ID
    */
   public @NonNull StartWorkflowOptions withDeduplicationId(@Nullable String deduplicationId) {
     return new StartWorkflowOptions(
@@ -182,8 +244,11 @@ public StartWorkflowOptions(@NonNull Queue queue) {
   }
 
   /**
-   * Produces a new StartWorkflowOptions that assigns a queue priority. Note that the queue must
-   * also be specified and have prioritization enabled
+   * Returns a new StartWorkflowOptions with the specified queue priority. Note: The queue must be
+   * specified and have prioritization enabled.
+   *
+   * @param priority the priority to assign
+   * @return a new StartWorkflowOptions with the updated priority
    */
   public @NonNull StartWorkflowOptions withPriority(@Nullable Integer priority) {
     return new StartWorkflowOptions(
@@ -198,7 +263,12 @@ public StartWorkflowOptions(@NonNull Queue queue) {
         this.appVersion);
   }
 
-  /** Produces a new StartWorkflowOptions that assigns a queue partition key */
+  /**
+   * Returns a new StartWorkflowOptions with the specified queue partition key.
+   *
+   * @param queuePartitionKey the partition key to assign
+   * @return a new StartWorkflowOptions with the updated partition key
+   */
   public @NonNull StartWorkflowOptions withQueuePartitionKey(@Nullable String queuePartitionKey) {
     return new StartWorkflowOptions(
         this.workflowId,
@@ -213,7 +283,10 @@ public StartWorkflowOptions(@NonNull Queue queue) {
   }
 
   /**
-   * Produces a new StartWorkflowOptions that assigns a delay before the workflow starts executing
+   * Returns a new StartWorkflowOptions with the specified delay before execution.
+   *
+   * @param delay the delay duration to assign
+   * @return a new StartWorkflowOptions with the updated delay
    */
   public @NonNull StartWorkflowOptions withDelay(@Nullable Duration delay) {
     return new StartWorkflowOptions(
@@ -228,7 +301,12 @@ public StartWorkflowOptions(@NonNull Queue queue) {
         this.appVersion);
   }
 
-  /** Produces a new StartWorkflowOptions that assigns an app version */
+  /**
+   * Returns a new StartWorkflowOptions with the specified application version.
+   *
+   * @param appVersion the application version to assign
+   * @return a new StartWorkflowOptions with the updated application version
+   */
   public @NonNull StartWorkflowOptions withAppVersion(@Nullable String appVersion) {
     return new StartWorkflowOptions(
         this.workflowId,
@@ -242,7 +320,11 @@ public StartWorkflowOptions(@NonNull Queue queue) {
         appVersion);
   }
 
-  /** Get the assigned workflow ID, replacing empty with null */
+  /**
+   * Get the assigned workflow ID, replacing empty with null.
+   *
+   * @return the workflow ID, or null if empty or not set
+   */
   @Override
   public @Nullable String workflowId() {
     return workflowId != null && workflowId.isEmpty() ? null : workflowId;

transact/src/main/kotlin/dev/dbos/transact/DBOSExtensions.kt

@@ -12,7 +12,6 @@ import dev.dbos.transact.workflow.WorkflowHandle
 // interfaces (like ThrowingSupplier), so such an extension would be unreachable — the Java member
 // wins before the extension is considered. This does not affect overloads that also take a
 // StartWorkflowOptions parameter, since those signatures are distinct from any Java member.
-// For the no-options case, we provide beginWorkflow as a uniquely-named alternative.
 
 /**
  * Starts a workflow using trailing lambda syntax, with the given [options].