temporalio · Sushisource · Mar 31, 2026 · Apr 2, 2026 · mjameswh · Mar 31, 2026
@@ -191,7 +191,7 @@ jobs:
       - name: Set up Java
         uses: actions/setup-java@v5
         with:
-          java-version: "11"
+          java-version: "23"
           distribution: "temurin"
 
       - name: Set up Gradle
@@ -200,6 +200,30 @@ jobs:
       - name: Run copyright and code format checks
         run: ./gradlew --no-daemon spotlessCheck
 
+  javadoc:
+    name: Javadoc
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+          submodules: recursive
+          ref: ${{ github.event.pull_request.head.sha }}
+
+      - name: Set up Java
+        uses: actions/setup-java@v5
+        with:
+          java-version: "23"
+          distribution: "temurin"
+
+      - name: Set up Gradle
+        uses: gradle/actions/setup-gradle@v5
+
+      - name: Run javadoc
+        run: ./gradlew --no-daemon javadoc
+
   build_native_images:
     name: Build native test server
     uses: ./.github/workflows/build-native-image.yml

@@ -18,4 +18,6 @@ src/main/idls/*
 .settings
 .vscode/
 */bin
-/.claude
+/.claude
+mise.local.toml
+**/.factorypath
@@ -32,9 +32,8 @@ subprojects {
 
     javadoc {
         options.encoding = 'UTF-8'
-        if (JavaVersion.current().isJava8Compatible()) {
-            options.addStringOption('Xdoclint:none', '-quiet')
-        }
+        options.addStringOption('Xdoclint:reference', '-quiet')
+        options.addBooleanOption('Werror', true)
         if (JavaVersion.current().isJava9Compatible()) {
             options.addBooleanOption('html5', true)
         }

@@ -172,7 +172,7 @@ public static ClientConfig fromToml(byte[] tomlData, ClientConfigFromTomlOptions
    *
    * @param config the client config to convert
    * @return the TOML data as bytes
-   * @apiNote The output will not be identical to the input if the config was loaded from a file
+   *     <p>Note: The output will not be identical to the input if the config was loaded from a file
    *     because comments and formatting are not preserved.
    */
   public static byte[] toTomlAsBytes(ClientConfig config) throws IOException {

@@ -11,8 +11,6 @@
 /**
  * Performs encoding/decoding of the payloads via the Remote Data Encoder (RDE) available over http.
  *
- * <p>
- *
  * <h2>Remote Data Encoder Http Server specification</h2>
  *
  * <p>RDE Server must:

@@ -126,8 +126,8 @@ public interface ActivityInfo {
   /**
    * Return the priority of the activity task.
    *
-   * @apiNote If unset or on an older server version, this method will return {@link
-   *     Priority#getDefaultInstance()}.
+   * <p>Note: If unset or on an older server version, this method will return {@link
+   * Priority#getDefaultInstance()}.
    */
   @Experimental
   @Nonnull

@@ -42,8 +42,6 @@
  * When <code>CImpl</code> instance is registered with the {@link io.temporal.worker.Worker} the
  * following activities are registered:
  *
- * <p>
- *
  * <ul>
  *   <li>B_a
  *   <li>B_b

@@ -158,9 +158,8 @@ static WorkflowClient newInstance(WorkflowServiceStubs service, WorkflowClientOp
    * @param workflowId Workflow id.
    * @param runId Run id of the workflow execution.
    * @return Stub that implements workflowInterface and can be used to signal, update, or query it.
-   * @deprecated Use {@link #newWorkflowStub(Class, WorkflowTargetOptions)} instead.
-   * @apiNote This method is deprecated because the returned stub does not properly account for the
-   *     runId.
+   * @deprecated Use {@link #newWorkflowStub(Class, WorkflowTargetOptions)} instead. This method is
+   *     deprecated because the returned stub does not properly account for the runId.
    */
   @Deprecated
   <T> T newWorkflowStub(Class<T> workflowInterface, String workflowId, Optional<String> runId);
@@ -205,9 +204,8 @@ static WorkflowClient newInstance(WorkflowServiceStubs service, WorkflowClientOp
    *     workflowId is assumed.
    * @param workflowType type of the workflow. Optional as it is used for error reporting only.
    * @return Stub that can be used to start workflow and later to signal or query it.
-   * @deprecated Use {@link #newUntypedWorkflowStub(WorkflowTargetOptions, Optional)} instead.
-   * @apiNote This method is deprecated because the returned stub does not properly account for the
-   *     runId.
+   * @deprecated Use {@link #newUntypedWorkflowStub(WorkflowTargetOptions, Optional)} instead. This
+   *     method is deprecated because the returned stub does not properly account for the runId.
    */
   @Deprecated
   WorkflowStub newUntypedWorkflowStub(
@@ -220,9 +218,8 @@ WorkflowStub newUntypedWorkflowStub(
    * @param execution workflow id and optional run id for execution
    * @param workflowType type of the workflow. Optional as it is used for error reporting only.
    * @return Stub that can be used to start workflow and later to signal or query it.
-   * @deprecated Use {@link #newUntypedWorkflowStub(WorkflowTargetOptions, Optional)} instead.
-   * @apiNote This method is deprecated because the returned stub does not properly account for the
-   *     runId.
+   * @deprecated Use {@link #newUntypedWorkflowStub(WorkflowTargetOptions, Optional)} instead. This
+   *     method is deprecated because the returned stub does not properly account for the runId.
    */
   WorkflowStub newUntypedWorkflowStub(WorkflowExecution execution, Optional<String> workflowType);
 

@@ -27,9 +27,9 @@
 /**
  * Plugin interface for customizing Temporal workflow client configuration.
  *
- * <p>This interface is separate from {@link
- * io.temporal.serviceclient.WorkflowServiceStubs.ServiceStubsPlugin} to allow plugins that only
- * need to configure the workflow client without affecting the underlying gRPC connection.
+ * <p>This interface is separate from {@link io.temporal.serviceclient.WorkflowServiceStubsPlugin}
+ * to allow plugins that only need to configure the workflow client without affecting the underlying
+ * gRPC connection.
  *
  * <p>Plugins that implement both {@code ServiceStubsPlugin} and {@code WorkflowClientPlugin} will
  * have their service stubs configuration applied when creating the service stubs, and their client
@@ -54,7 +54,7 @@
  * }
  * }</pre>
  *
- * @see io.temporal.serviceclient.WorkflowServiceStubs.ServiceStubsPlugin
+ * @see io.temporal.serviceclient.WorkflowServiceStubsPlugin
  * @see io.temporal.worker.WorkerPlugin
  * @see SimplePlugin
  */

@@ -22,8 +22,8 @@ public WorkflowExecutionDescription(
   /**
    * Get the fixed summary for this workflow execution.
    *
-   * @apiNote Will be decoded on each invocation, so it is recommended to cache the result if it is
-   *     used multiple times.
+   * <p>Note: Will be decoded on each invocation, so it is recommended to cache the result if it is
+   * used multiple times.
    */
   @Experimental
   @Nullable
@@ -45,8 +45,8 @@ public String getStaticSummary() {
   /**
    * Get the details summary for this workflow execution.
    *
-   * @apiNote Will be decoded on each invocation, so it is recommended to cache the result if it is
-   *     used multiple times.
+   * <p>Note: Will be decoded on each invocation, so it is recommended to cache the result if it is
+   * used multiple times.
    */
   @Experimental
   @Nullable

@@ -162,7 +162,7 @@ public Builder setWorkflowId(String workflowId) {
     /**
      * Specifies server behavior if a completed workflow with the same id exists. Note that under no
      * conditions Temporal allows two workflows with the same namespace and workflow id run
-     * simultaneously. See {@line setWorkflowIdConflictPolicy} for handling a workflow id
+     * simultaneously. See {@link #setWorkflowIdConflictPolicy} for handling a workflow id
      * duplication with a <b>Running</b> workflow.
      *
      * <p>Default value if not set: <b>AllowDuplicate</b>

@@ -269,12 +269,13 @@ <R> R getResult(long timeout, TimeUnit unit, Class<R> resultClass, Type resultTy
    * to complete. Behind the scenes this call performs long polls the Temporal Server waiting for
    * workflow completion.
    *
+   * <p>See {@link #getResult(Class)} as a sync version of this method for detailed information
+   * about exceptions that may be thrown from {@link CompletableFuture#get()} wrapped by {@link
+   * ExecutionException}.
+   *
    * @param resultClass class of the workflow return value
    * @param <R> type of the workflow return value
    * @return future completed with workflow return value or an exception
-   * @see #getResult(Class) as a sync version of this method for detailed information about
-   *     exceptions that may be thrown from {@link CompletableFuture#get()} wrapped by {@link
-   *     ExecutionException}
    */
   <R> CompletableFuture<R> getResultAsync(Class<R> resultClass);
 
@@ -283,14 +284,15 @@ <R> R getResult(long timeout, TimeUnit unit, Class<R> resultClass, Type resultTy
    * to complete. Behind the scene this call performs long poll on Temporal service waiting for
    * workflow completion notification.
    *
+   * <p>See {@link #getResult(Class, Type)} as a sync version of this method for detailed
+   * information about exceptions that may be thrown from {@link CompletableFuture#get()} wrapped by
+   * {@link ExecutionException}.
+   *
    * @param resultClass class of the workflow return value
    * @param resultType type of the workflow return value. Differs from {@code resultClass} for
    *     generic types.
    * @param <R> type of the workflow return value
    * @return future completed with workflow return value or an exception
-   * @see #getResult(Class, Type) as a sync version of this method for detailed information about
-   *     exceptions that may be thrown from {@link CompletableFuture#get()} wrapped by {@link
-   *     ExecutionException}
    */
   <R> CompletableFuture<R> getResultAsync(Class<R> resultClass, Type resultType);
 
@@ -299,14 +301,15 @@ <R> R getResult(long timeout, TimeUnit unit, Class<R> resultClass, Type resultTy
    * to complete. Behind the scene this call performs long poll on Temporal service waiting for
    * workflow completion notification.
    *
+   * <p>See {@link #getResult(long, TimeUnit, Class)} as a sync version of this method for detailed
+   * information about exceptions that may be thrown from {@link CompletableFuture#get()} wrapped by
+   * {@link ExecutionException}.
+   *
    * @param timeout maximum time to wait and perform a background long poll
    * @param unit unit of timeout
    * @param resultClass class of the workflow return value
    * @param <R> type of the workflow return value
    * @return future completed with workflow return value or an exception
-   * @see #getResult(long, TimeUnit, Class) as a sync version of this method for detailed
-   *     information about exceptions that may be thrown from {@link CompletableFuture#get()}
-   *     wrapped by {@link ExecutionException}
    */
   <R> CompletableFuture<R> getResultAsync(long timeout, TimeUnit unit, Class<R> resultClass);
 
@@ -315,16 +318,17 @@ <R> R getResult(long timeout, TimeUnit unit, Class<R> resultClass, Type resultTy
    * to complete. Behind the scene this call performs long poll on Temporal service waiting for
    * workflow completion notification.
    *
+   * <p>See {@link #getResult(long, TimeUnit, Class, Type)} as a sync version of this method for
+   * detailed information about exceptions that may be thrown from {@link CompletableFuture#get()}
+   * wrapped by {@link ExecutionException}.
+   *
    * @param timeout maximum time to wait and perform a background long poll
    * @param unit unit of timeout
    * @param resultClass class of the workflow return value
    * @param resultType type of the workflow return value. Differs from {@code resultClass} for
    *     generic types.
    * @param <R> type of the workflow return value
    * @return future completed with workflow return value or an exception
-   * @see #getResult(long, TimeUnit, Class, Type) as a sync version of this method for detailed
-   *     information about exceptions that may be thrown from {@link CompletableFuture#get()}
-   *     wrapped by {@link ExecutionException}
    */
   <R> CompletableFuture<R> getResultAsync(
       long timeout, TimeUnit unit, Class<R> resultClass, Type resultType);

@@ -51,9 +51,9 @@ public <T> Builder setWorkflowType(Class<T> workflowInterface) {
     /**
      * Set the workflow options to use when starting a workflow action.
      *
-     * @note ID and TaskQueue are required. Some options like ID reuse policy, cron schedule, and
-     *     start signal cannot be set or an error will occur. Schedules requires the use of typed
-     *     search attributes and untyped search attributes will be ignored.
+     * <p>Note: ID and TaskQueue are required. Some options like ID reuse policy, cron schedule, and
+     * start signal cannot be set or an error will occur. Schedules requires the use of typed search
+     * attributes and untyped search attributes will be ignored.
      */
     public Builder setOptions(WorkflowOptions options) {
       this.options = options;

@@ -21,8 +21,8 @@
  * <p>The implementation must forward all the calls to {@code next}, but it may change the input
  * parameters.
  *
- * @see WorkerInterceptor#interceptWorkflow(WorkflowInboundCallsInterceptor) for a definition of
- *     "next" {@link WorkflowInboundCallsInterceptor}
+ * <p>See {@link WorkerInterceptor#interceptWorkflow(WorkflowInboundCallsInterceptor)} for a
+ * definition of "next" {@link WorkflowInboundCallsInterceptor}.
  */
 @Experimental
 public interface WorkflowInboundCallsInterceptor {
@@ -166,10 +166,11 @@ public Object getResult() {
    *
    * <p>The instance should be passed into the {next.init(newWorkflowOutboundCallsInterceptor)}.
    *
+   * <p>See {@link WorkerInterceptor#interceptWorkflow} for the definition of "next" {@link
+   * WorkflowInboundCallsInterceptor}.
+   *
    * @param outboundCalls an existing interceptor instance to be proxied by the interceptor created
    *     inside this method
-   * @see WorkerInterceptor#interceptWorkflow for the definition of "next" {@link
-   *     WorkflowInboundCallsInterceptor}
    */
   void init(WorkflowOutboundCallsInterceptor outboundCalls);
 

@@ -33,8 +33,8 @@
  * implementation must forward all the calls to the outbound interceptor passed as a {@code
  * outboundCalls} parameter to the {@code init} call.
  *
- * @see WorkerInterceptor#interceptWorkflow for the definition of "next" {@link
- *     WorkflowInboundCallsInterceptor}.
+ * @see WorkerInterceptor#interceptWorkflow for the definition of "next"
+ *     WorkflowInboundCallsInterceptor.
  */
 @Experimental
 public interface WorkflowOutboundCallsInterceptor {

@@ -1,7 +1,7 @@
 /**
  * This package and its subpackages contain implementation classes of the Temporal SDK.
  *
- * <p><strong></strong>Do not use them directly in any application code! There is absolutely no
- * guarantee about backwards compatibility of APIs in the internal packages.</strong>
+ * <p><strong>Do not use them directly in any application code! There is absolutely no guarantee
+ * about backwards compatibility of APIs in the internal packages.</strong>
  */
 package io.temporal.internal;
@@ -4,7 +4,7 @@
 
 /**
  * Internal delegate for virtual thread handling on JDK 21. This is a dummy version for reachability
- * on JDK <21.
+ * on JDK &lt;21.
  */
 public final class VirtualThreadDelegate {
   public static ExecutorService newVirtualThreadExecutor(ThreadConfigurator configurator) {

@@ -254,8 +254,6 @@ public <R> void addWorkflowImplementationFactory(
    * <p>This method is misaligned with other workflow implementation registration methods in this
    * aspect.
    *
-   * <p></font>
-   *
    * @deprecated Use {@link #registerWorkflowImplementationFactory(Class, Func,
    *     WorkflowImplementationOptions)} with {@code
    *     WorkflowImplementationOptions.newBuilder().setFailWorkflowExceptionTypes(Throwable.class).build()}
@@ -304,8 +302,6 @@ public <R> void addWorkflowImplementationFactory(Class<R> workflowInterface, Fun
    * instances is allowed. This way, the configuration is persisted into the history and maintained
    * same during replay.
    *
-   * <p></font>
-   *
    * @param workflowInterface Workflow interface that this factory implements
    * @param factory should create a new instance of the workflow implementation object every time
    *     it's called

@@ -107,9 +107,9 @@ public Builder setWorkerInterceptors(WorkerInterceptor... workerInterceptors) {
      * Sets the worker plugins to use with workers created by this factory. Plugins can modify
      * worker configuration and wrap worker lifecycle.
      *
-     * <p>Note: Plugins that implement both {@link io.temporal.client.ClientPlugin} and {@link
-     * WorkerPlugin} are automatically propagated from the client. Use this method for worker-only
-     * plugins that don't need client-side configuration.
+     * <p>Note: Plugins that implement both {@link io.temporal.client.WorkflowClientPlugin} and
+     * {@link WorkerPlugin} are automatically propagated from the client. Use this method for
+     * worker-only plugins that don't need client-side configuration.
      *
      * @param plugins the worker plugins to use
      * @return this builder for chaining

@@ -30,7 +30,7 @@
 /**
  * Plugin interface for customizing Temporal worker configuration and lifecycle.
  *
- * <p>Plugins that also implement {@link io.temporal.client.ClientPlugin} are automatically
+ * <p>Plugins that also implement {@link io.temporal.client.WorkflowClientPlugin} are automatically
  * propagated from the client to workers created from that client.
  *
  * <p>Example implementation:
@@ -61,7 +61,7 @@
  * }
  * }</pre>
  *
- * @see io.temporal.client.ClientPlugin
+ * @see io.temporal.client.WorkflowClientPlugin
  * @see SimplePlugin
  */
 @Experimental

@@ -78,7 +78,8 @@ public interface DispatchCallback extends Function<WorkflowTask, Boolean> {
      *
      * @param workflowTask WorkflowTask to be dispatched
      * @return true if the dispatch was successful and false otherwise
-     * @throws IllegalArgumentException if {@code workflowTask} doesn't belong to the task queue of the Worker that provided the {@link WorkflowTaskDispatchHandle
+     * @throws IllegalArgumentException if {@code workflowTask} doesn't belong to the task queue of
+     *     the Worker that provided the {@link WorkflowTaskDispatchHandle}
      */
     @Override
     Boolean apply(WorkflowTask workflowTask) throws IllegalArgumentException;

@@ -9,7 +9,7 @@ public interface SlotReserveContext<SI extends SlotInfo> {
   String getTaskQueue();
 
   /**
-   * @return A read-only & safe for concurrent access mapping of slot permits to the information
+   * @return A read-only &amp; safe for concurrent access mapping of slot permits to the information
    *     associated with the in-use slot. This map is changed internally any time new slots are
    *     used.
    */
-Original file line number
+Diff line change
@@ Expand Up / @@ -11,8 +11,6 @@ @@
     /**
      * Performs encoding/decoding of the payloads via the Remote Data Encoder (RDE) available over http.
      *
-     * <p>
-     *
      * <h2>Remote Data Encoder Http Server specification</h2>
      *
      * <p>RDE Server must:
@@ Expand Down @@