Generates proper documentation for classes and properties (#1418)

Author: jderusse

src/Enum/ValidationExceptionReason.php

@@ -2,9 +2,6 @@
 
 namespace AsyncAws\StepFunctions\Enum;
 
-/**
- * The input does not satisfy the constraints specified by an Amazon Web Services service.
- */
 final class ValidationExceptionReason
 {
     public const API_DOES_NOT_SUPPORT_LABELED_ARNS = 'API_DOES_NOT_SUPPORT_LABELED_ARNS';

src/Input/SendTaskFailureInput.php

@@ -11,9 +11,9 @@ final class SendTaskFailureInput extends Input
 {
     /**
      * The token that represents this task. Task tokens are generated by Step Functions when tasks are assigned to a worker,
-     * or in the context object when a workflow enters a task state. See GetActivityTaskOutput$taskToken.
+     * or in the context object [^1] when a workflow enters a task state. See GetActivityTaskOutput$taskToken.
      *
-     * @see https://docs.aws.amazon.com/step-functions/latest/dg/input-output-contextobject.html
+     * [^1]: https://docs.aws.amazon.com/step-functions/latest/dg/input-output-contextobject.html
      *
      * @required
      *

src/Input/SendTaskHeartbeatInput.php

@@ -11,9 +11,9 @@ final class SendTaskHeartbeatInput extends Input
 {
     /**
      * The token that represents this task. Task tokens are generated by Step Functions when tasks are assigned to a worker,
-     * or in the context object when a workflow enters a task state. See GetActivityTaskOutput$taskToken.
+     * or in the context object [^1] when a workflow enters a task state. See GetActivityTaskOutput$taskToken.
      *
-     * @see https://docs.aws.amazon.com/step-functions/latest/dg/input-output-contextobject.html
+     * [^1]: https://docs.aws.amazon.com/step-functions/latest/dg/input-output-contextobject.html
      *
      * @required
      *

src/Input/SendTaskSuccessInput.php

@@ -11,9 +11,9 @@ final class SendTaskSuccessInput extends Input
 {
     /**
      * The token that represents this task. Task tokens are generated by Step Functions when tasks are assigned to a worker,
-     * or in the context object when a workflow enters a task state. See GetActivityTaskOutput$taskToken.
+     * or in the context object [^1] when a workflow enters a task state. See GetActivityTaskOutput$taskToken.
      *
-     * @see https://docs.aws.amazon.com/step-functions/latest/dg/input-output-contextobject.html
+     * [^1]: https://docs.aws.amazon.com/step-functions/latest/dg/input-output-contextobject.html
      *
      * @required
      *

src/Input/StartExecutionInput.php

@@ -20,10 +20,24 @@ final class StartExecutionInput extends Input
 
     /**
      * The name of the execution. This name must be unique for your Amazon Web Services account, region, and state machine
-     * for 90 days. For more information, see  Limits Related to State Machine Executions in the *Step Functions Developer
-     * Guide*.
+     * for 90 days. For more information, see  Limits Related to State Machine Executions [^1] in the *Step Functions
+     * Developer Guide*.
      *
-     * @see https://docs.aws.amazon.com/step-functions/latest/dg/limits.html#service-limits-state-machine-executions
+     * A name must *not* contain:
+     *
+     * - white space
+     * -
+     * - brackets `< > { } [ ]`
+     * -
+     * - wildcard characters `? *`
+     * -
+     * - special characters `" # % \ ^ | ~ ` $ & , ; : /`
+     * -
+     * - control characters (`U+0000-001F`, `U+007F-009F`)
+     *
+     * To enable logging with CloudWatch Logs, the name should only contain 0-9, A-Z, a-z, - and _.
+     *
+     * [^1]: https://docs.aws.amazon.com/step-functions/latest/dg/limits.html#service-limits-state-machine-executions
      *
      * @var string|null
      */
@@ -32,6 +46,12 @@ final class StartExecutionInput extends Input
     /**
      * The string that contains the JSON input data for the execution, for example:.
      *
+     * `"input": "{\"first_name\" : \"test\"}"`
+     *
+     * > If you don't include any JSON input data, you still must include the two braces, for example: `"input": "{}"`
+     *
+     * Length constraints apply to the payload size, and are expressed as bytes in UTF-8 encoding.
+     *
      * @var string|null
      */
     private $input;

src/StepFunctionsClient.php

@@ -34,10 +34,11 @@
 class StepFunctionsClient extends AbstractApi
 {
     /**
-     * Used by activity workers and task states using the callback pattern to report that the task identified by the
+     * Used by activity workers and task states using the callback [^1] pattern to report that the task identified by the
      * `taskToken` failed.
      *
-     * @see https://docs.aws.amazon.com/step-functions/latest/dg/connect-to-resource.html#connect-wait-token
+     * [^1]: https://docs.aws.amazon.com/step-functions/latest/dg/connect-to-resource.html#connect-wait-token
+     *
      * @see https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskFailure.html
      * @see https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-states-2016-11-23.html#sendtaskfailure
      *
@@ -66,16 +67,21 @@ public function sendTaskFailure($input): SendTaskFailureOutput
     }
 
     /**
-     * Used by activity workers and task states using the callback pattern to report to Step Functions that the task
+     * Used by activity workers and task states using the callback [^1] pattern to report to Step Functions that the task
      * represented by the specified `taskToken` is still making progress. This action resets the `Heartbeat` clock. The
      * `Heartbeat` threshold is specified in the state machine's Amazon States Language definition (`HeartbeatSeconds`).
      * This action does not in itself create an event in the execution history. However, if the task times out, the
      * execution history contains an `ActivityTimedOut` entry for activities, or a `TaskTimedOut` entry for for tasks using
-     * the job run or callback pattern.
+     * the job run [^2] or callback [^3] pattern.
+     *
+     * > The `Timeout` of a task, defined in the state machine's Amazon States Language definition, is its maximum allowed
+     * > duration, regardless of the number of SendTaskHeartbeat requests received. Use `HeartbeatSeconds` to configure the
+     * > timeout interval for heartbeats.
+     *
+     * [^1]: https://docs.aws.amazon.com/step-functions/latest/dg/connect-to-resource.html#connect-wait-token
+     * [^2]: https://docs.aws.amazon.com/step-functions/latest/dg/connect-to-resource.html#connect-sync
+     * [^3]: https://docs.aws.amazon.com/step-functions/latest/dg/connect-to-resource.html#connect-wait-token
      *
-     * @see https://docs.aws.amazon.com/step-functions/latest/dg/connect-to-resource.html#connect-wait-token
-     * @see https://docs.aws.amazon.com/step-functions/latest/dg/connect-to-resource.html#connect-sync
-     * @see https://docs.aws.amazon.com/step-functions/latest/dg/connect-to-resource.html#connect-wait-token
      * @see https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskHeartbeat.html
      * @see https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-states-2016-11-23.html#sendtaskheartbeat
      *
@@ -102,10 +108,11 @@ public function sendTaskHeartbeat($input): SendTaskHeartbeatOutput
     }
 
     /**
-     * Used by activity workers and task states using the callback pattern to report that the task identified by the
+     * Used by activity workers and task states using the callback [^1] pattern to report that the task identified by the
      * `taskToken` completed successfully.
      *
-     * @see https://docs.aws.amazon.com/step-functions/latest/dg/connect-to-resource.html#connect-wait-token
+     * [^1]: https://docs.aws.amazon.com/step-functions/latest/dg/connect-to-resource.html#connect-wait-token
+     *
      * @see https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskSuccess.html
      * @see https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-states-2016-11-23.html#sendtasksuccess
      *
@@ -138,6 +145,17 @@ public function sendTaskSuccess($input): SendTaskSuccessOutput
      * Starts a state machine execution. If the given state machine Amazon Resource Name (ARN) is a qualified state machine
      * ARN, it will fail with ValidationException.
      *
+     * A qualified state machine ARN refers to a *Distributed Map state* defined within a state machine. For example, the
+     * qualified state machine ARN `arn:partition:states:region:account-id:stateMachine:stateMachineName/mapStateLabel`
+     * refers to a *Distributed Map state* with a label `mapStateLabel` in the state machine named `stateMachineName`.
+     *
+     * > `StartExecution` is idempotent for `STANDARD` workflows. For a `STANDARD` workflow, if `StartExecution` is called
+     * > with the same name and input as a running execution, the call will succeed and return the same response as the
+     * > original request. If the execution is closed or if the input is different, it will return a `400
+     * > ExecutionAlreadyExists` error. Names can be reused after 90 days.
+     * >
+     * > `StartExecution` is not idempotent for `EXPRESS` workflows.
+     *
      * @see https://docs.aws.amazon.com/step-functions/latest/apireference/API_StartExecution.html
      * @see https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-states-2016-11-23.html#startexecution
      *
@@ -179,6 +197,8 @@ public function startExecution($input): StartExecutionOutput
     /**
      * Stops an execution.
      *
+     * This API action is not supported by `EXPRESS` state machines.
+     *
      * @see https://docs.aws.amazon.com/step-functions/latest/apireference/API_StopExecution.html
      * @see https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-states-2016-11-23.html#stopexecution
      *