From ff333ca7d6d7094f07b41c2a92f34a5ba11148d7 Mon Sep 17 00:00:00 2001
From: Quinn Klassen <klassenq@gmail.com>
Date: Mon, 6 Jan 2025 14:57:56 -0800
Subject: [PATCH] Add javadocs for ActivityCompletionClient (#2353)

---
 .../ManualActivityCompletionClient.java       |  7 ++-
 .../client/ActivityCompletionClient.java      | 55 +++++++++++++++++++
 2 files changed, 61 insertions(+), 1 deletion(-)

diff --git a/temporal-sdk/src/main/java/io/temporal/activity/ManualActivityCompletionClient.java b/temporal-sdk/src/main/java/io/temporal/activity/ManualActivityCompletionClient.java
index 412e9780c..2eb71e79a 100644
--- a/temporal-sdk/src/main/java/io/temporal/activity/ManualActivityCompletionClient.java
+++ b/temporal-sdk/src/main/java/io/temporal/activity/ManualActivityCompletionClient.java
@@ -46,12 +46,17 @@ public interface ManualActivityCompletionClient {
    */
   void fail(@Nonnull Throwable failure);
 
+  /**
+   * Records heartbeat for an activity
+   *
+   * @param details to record with the heartbeat
+   */
   void recordHeartbeat(@Nullable Object details) throws CanceledFailure;
 
   /**
    * Confirms successful cancellation to the server.
    *
-   * @param details
+   * @param details to record with the cancellation
    */
   void reportCancellation(@Nullable Object details);
 }
diff --git a/temporal-sdk/src/main/java/io/temporal/client/ActivityCompletionClient.java b/temporal-sdk/src/main/java/io/temporal/client/ActivityCompletionClient.java
index de7a59ddc..6a76bbbbc 100644
--- a/temporal-sdk/src/main/java/io/temporal/client/ActivityCompletionClient.java
+++ b/temporal-sdk/src/main/java/io/temporal/client/ActivityCompletionClient.java
@@ -38,26 +38,81 @@
  */
 public interface ActivityCompletionClient {
 
+  /**
+   * Completes the activity execution successfully.
+   *
+   * @param taskToken token of the activity attempt to complete
+   * @param result of the activity execution
+   */
   <R> void complete(byte[] taskToken, R result) throws ActivityCompletionException;
 
+  /**
+   * Completes the activity execution successfully.
+   *
+   * @param workflowId id of the workflow that started the activity
+   * @param runId optional run id of the workflow that started the activity
+   * @param activityId id of the activity
+   * @param result of the activity execution
+   */
   <R> void complete(String workflowId, Optional<String> runId, String activityId, R result)
       throws ActivityCompletionException;
 
+  /**
+   * Completes the activity execution with failure.
+   *
+   * @param taskToken token of the activity attempt to complete
+   * @param result the exception to be used as a failure details object
+   */
   void completeExceptionally(byte[] taskToken, Exception result) throws ActivityCompletionException;
 
+  /**
+   * Completes the activity execution with failure.
+   *
+   * @param workflowId id of the workflow that started the activity
+   * @param runId optional run id of the workflow that started the activity
+   * @param activityId id of the activity
+   * @param result the exception to be used as a failure details object
+   */
   void completeExceptionally(
       String workflowId, Optional<String> runId, String activityId, Exception result)
       throws ActivityCompletionException;
 
+  /**
+   * Confirms successful cancellation to the server.
+   *
+   * @param taskToken token of the activity attempt
+   * @param details details to record with the cancellation
+   */
   <V> void reportCancellation(byte[] taskToken, V details) throws ActivityCompletionException;
 
+  /**
+   * Confirms successful cancellation to the server.
+   *
+   * @param workflowId id of the workflow that started the activity
+   * @param runId optional run id of the workflow that started the activity
+   * @param activityId id of the activity
+   * @param details details to record with the cancellation
+   */
   <V> void reportCancellation(
       String workflowId, Optional<String> runId, String activityId, V details)
       throws ActivityCompletionException;
 
+  /**
+   * Records a heartbeat for an activity.
+   *
+   * @param taskToken token of the activity attempt
+   * @param details details to record with the heartbeat
+   * @throws ActivityCompletionException if activity should stop executing
+   */
   <V> void heartbeat(byte[] taskToken, V details) throws ActivityCompletionException;
 
   /**
+   * Records a heartbeat for an activity.
+   *
+   * @param workflowId id of the workflow that started the activity
+   * @param runId optional run id of the workflow that started the activity
+   * @param activityId id of the activity
+   * @param details details to record with the heartbeat
    * @throws ActivityCompletionException if activity should stop executing
    */
   <V> void heartbeat(String workflowId, Optional<String> runId, String activityId, V details)