Docstring edits

temporal-sdk/src/main/java/io/temporal/activity/ActivityExecutionContext.java

@@ -143,7 +143,7 @@ public interface ActivityExecutionContext {
   Scope getMetricsScope();
 
   /**
-   * Get a {@link WorkflowClient} that can be used to start interact with the Temporal service from
+   * Get a {@link WorkflowClient} that can be used to interact with the Temporal service from
    * an activity.
    */
   WorkflowClient getWorkflowClient();

temporal-sdk/src/main/java/io/temporal/internal/replay/ReplayWorkflowTaskHandler.java

@@ -119,18 +119,16 @@ private Result handleWorkflowTaskWithQuery(
       Result result;
 
       if (directQuery) {
-        // Direct query happens when there is no reason (events) to produce a real persisted
-        // workflow task.
-        // But Server needs to notify the workflow about the query and get back the query result.
-        // Server creates a fake non-persisted a PollWorkflowTaskResponse with just the query.
-        // This WFT has no new events in the history to process
-        // and the worker response on such a WFT can't contain any new commands either.
+        // A direct query is when the server needs to notify the workflow about queries (and get back the query
+        // results), but there are no new events in history. In this situation the server creates a
+        // PollWorkflowTaskResponse (i.e. a WFT) with the queries but without new events in the history. The worker
+        // response to such a WFT may not contain any new commands.
         QueryResult queryResult =
             workflowRunTaskHandler.handleDirectQueryWorkflowTask(workflowTask, historyIterator);
         finalCommand = queryResult.isWorkflowMethodCompleted();
         result = createDirectQueryResult(workflowTask, queryResult, null);
       } else {
-        // main code path, handle workflow task that can have an embedded query
+        // Main code path; handle workflow task (with events, and perhaps also queries).
         WorkflowTaskResult wftResult =
             workflowRunTaskHandler.handleWorkflowTask(workflowTask, historyIterator);
         finalCommand = wftResult.isFinalCommand();

temporal-sdk/src/main/java/io/temporal/internal/statemachines/WorkflowStateMachines.java

@@ -484,14 +484,14 @@ private void handleSingleEvent(HistoryEvent event, boolean lastTask, boolean has
   }
 
   /**
-   * Handles command event. Command event is an event which is generated from a command emitted by a
-   * past decision. Each command has a correspondent event. For example ScheduleActivityTaskCommand
-   * is recorded to the history as ActivityTaskScheduledEvent.
+   * Handle a command event. A command event is an event which was generated by a command emitted by
+   * a past event. Each command has precisely one corresponding event. For example a
+   * ScheduleActivityTask command gives rise to an ActivityTaskScheduled history event.
    *
-   * <p>Command events always follow WorkflowTaskCompletedEvent.
+   * <p>Command events always follow a WorkflowTaskCompleted event.
    *
-   * <p>The handling consists from verifying that the next command in the commands queue matches the
-   * event, command state machine is notified about the event and the command is removed from the
+   * <p>The handling consists of verifying that the next command in the commands queue matches the
+   * event. The command state machine is notified about the event and the command is removed from the
    * commands queue.
    */
   private void handleCommandEvent(HistoryEvent event) {

temporal-sdk/src/main/java/io/temporal/workflow/ActivityStub.java

@@ -23,14 +23,14 @@
 import java.lang.reflect.Type;
 
 /**
- * ActivityStub is used to call an activity without referencing an interface it implements. This is
- * useful to call activities when their type is not known at compile time or to execute activities
+ * ActivityStub is used to call an activity without referencing an interface that it implements. This is
+ * useful for calling activities when their type is not known at compile time, or for executing activities
  * implemented in other languages. Created through {@link Workflow#newActivityStub(Class)}.
  */
 public interface ActivityStub {
 
   /**
-   * Executes an activity by its type name and arguments. Blocks until the activity completion.
+   * Executes an activity by its type name and arguments. Blocks until activity completion.
    *
    * @param activityName name of an activity type to execute.
    * @param resultClass the expected return type of the activity. Use Void.class for activities that
@@ -42,7 +42,7 @@ public interface ActivityStub {
   <R> R execute(String activityName, Class<R> resultClass, Object... args);
 
   /**
-   * Executes an activity by its type name and arguments. Blocks until the activity completion.
+   * Executes an activity by its type name and arguments. Blocks until activity completion.
    *
    * @param activityName name of an activity type to execute.
    * @param resultClass the expected return class of the activity. Use Void.class for activities

temporal-sdk/src/main/java/io/temporal/workflow/Async.java

@@ -29,7 +29,7 @@
 public final class Async {
 
   /**
-   * Invokes zero argument function asynchronously.
+   * Invokes a zero-argument function asynchronously.
    *
    * @param function Function to execute asynchronously
    * @return promise that contains function result or failure
@@ -39,7 +39,7 @@ public static <R> Promise<R> function(Functions.Func<R> function) {
   }
 
   /**
-   * Invokes one argument function asynchronously.
+   * Invokes a one-argument function asynchronously.
    *
    * @param function Function to execute asynchronously
    * @param arg1 first function argument