Merge pull request #407: Add generation of API documentation

temporalio · Mar 20, 2024 · 403603f · 403603f
2 parents d230c85 + 3161064
commit 403603f
Show file tree

Hide file tree

Showing 59 changed files with 569 additions and 278 deletions.
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -0,0 +1,35 @@
+name: Generating API documentation
+
+on:
+  push:
+    branches:
+      - 'master'
+      - 'api-reference'
+
+jobs:
+  docs:
+    name: Generating API documentation
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - uses: actions/setup-node@v1
+        with:
+          node-version: 20
+
+      - name: Cache phpDocumentor build files
+        id: phpdocumentor-cache
+        uses: actions/cache@v3
+        with:
+          path: .phpdoc/cache
+          key: ${{ runner.os }}-phpdocumentor-${{ github.sha }}
+          restore-keys: |
+            ${{ runner.os }}-phpdocumentor-
+
+      - name: Build with documentation
+        run: docker run --rm --volume "$(pwd):/data" phpdoc/phpdoc:3.4 -vv --template default
+
+      - name: Upload documentation
+        run: npx vercel deploy docs/api -t ${{ secrets.VERCEL_TOKEN }} --name php --scope temporal --prod --yes
diff --git a/phpdoc.dist.xml b/phpdoc.dist.xml
@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<phpdocumentor
+    configVersion="3"
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xmlns="https://www.phpdoc.org"
+    xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/phpDocumentor/phpDocumentor/master/data/xsd/phpdoc.xsd"
+>
+    <paths>
+        <output>docs/api</output>
+        <cache>.phpdoc/cache</cache>
+    </paths>
+    <version number="latest">
+        <api>
+            <source dsn=".">
+                <path>src</path>
+            </source>
+            <ignore hidden="true" symlinks="true">
+                <path>src/Internal/**/*</path>
+            </ignore>
+        </api>
+    </version>
+</phpdocumentor>
diff --git a/src/Activity.php b/src/Activity.php
@@ -42,7 +42,7 @@ public static function getInfo(): ActivityInfo
      *
      * The data is equivalent to what is passed to the activity method handler.
      *
-     * <code>
+     * ```php
      *  #[ActivityMethod]
      *  public function activityMethod(int $first, string $second)
      *  {
@@ -51,7 +51,7 @@ public static function getInfo(): ActivityInfo
      *      Assert::assertTrue($first,  $arguments->getValue(0, Type::TYPE_INT));
      *      Assert::assertTrue($second, $arguments->getValue(1, Type::TYPE_STRING));
      *  }
-     * </code>
+     * ```
      *
      * @return ValuesInterface
      * @throws OutOfContextException in the absence of the activity execution context.
@@ -65,8 +65,9 @@ public static function getInput(): ValuesInterface
     }
 
     /**
-     * Returns {@see true} when heartbeat's ({@see Activity::heartbeat()}) first
-     * argument has been passed.
+     * Check if the heartbeat's first argument has been passed.
+     *
+     * This method returns **true** if the first argument has been passed to the {@see Activity::heartbeat()} method.
      *
      * @return bool
      * @throws OutOfContextException in the absence of the activity execution context.
@@ -80,8 +81,9 @@ public static function hasHeartbeatDetails(): bool
     }
 
     /**
-     * The method returns payload that has been passed into last
-     * heartbeat ({@see Activity::heartbeat()}) method.
+     * Returns the payload passed into the last heartbeat.
+     *
+     * This method retrieves the payload that was passed into the last call of the {@see Activity::heartbeat()} method.
      *
      * @param Type|string|\ReflectionType|\ReflectionClass|null $type
      * @return mixed
@@ -96,6 +98,8 @@ public static function getHeartbeatDetails($type = null)
     }
 
     /**
+     * Marks the activity as incomplete for asynchronous completion.
+     *
      * If this method is called during an activity execution then activity is
      * not going to complete when its method returns. It is expected to be
      * completed asynchronously using {@see ActivityCompletionClientInterface::complete()}.
@@ -113,7 +117,7 @@ public static function doNotCompleteOnReturn(): void
     /**
      * Use to notify workflow that activity execution is alive.
      *
-     * <code>
+     * ```php
      *  public function activityMethod()
      *  {
      *      // An example method of deferred request
@@ -127,7 +131,7 @@ public static function doNotCompleteOnReturn(): void
      *      // Returns response of deferred request
      *      return $query->getResult();
      *  }
-     * </code>
+     * ```
      *
      * @param mixed $details In case of activity timeout details are returned
      * as a field of the exception thrown.

diff --git a/src/Activity/ActivityCancellationType.php b/src/Activity/ActivityCancellationType.php
@@ -15,9 +15,10 @@
 use Temporal\Internal\Marshaller\Type\Type;
 
 /**
- * Defines behaviour of the parent workflow when {@see CancellationScope} that
- * wraps child workflow execution request is canceled. The result of the
- * cancellation independently of the type is a {@see FailedCancellationException}
+ * Defines behaviour of the parent workflow when `CancellationScope` that
+ * wraps child workflow execution request is canceled.
+ *
+ * The result of the cancellation independently of the type is a {@see FailedCancellationException}
  * thrown from the child workflow method.
  *
  * @extends Type<bool>
@@ -44,17 +45,11 @@ final class ActivityCancellationType extends Type
      */
     public const ABANDON = 0x02;
 
-    /**
-     * {@inheritDoc}
-     */
     public function parse($value, $current)
     {
         return $value ? self::WAIT_CANCELLATION_COMPLETED : self::TRY_CANCEL;
     }
 
-    /**
-     * {@inheritDoc}
-     */
     public function serialize($value): bool
     {
         switch ($value) {

diff --git a/src/Activity/ActivityContextInterface.php b/src/Activity/ActivityContextInterface.php
@@ -18,27 +18,35 @@
 interface ActivityContextInterface
 {
     /**
+     * Returns information about current activity execution.
+     *
      * @see Activity::getInfo()
      *
      * @return ActivityInfo
      */
     public function getInfo(): ActivityInfo;
 
     /**
+     * Returns activity execution input arguments.
+     *
      * @see Activity::getInput()
      *
      * @return ValuesInterface
      */
     public function getInput(): ValuesInterface;
 
     /**
+     * Check if the heartbeat's first argument has been passed.
+     *
      * @see Activity::hasHeartbeatDetails()
      *
      * @return bool
      */
     public function hasHeartbeatDetails(): bool;
 
     /**
+     * Returns the payload passed into the last heartbeat.
+     *
      * @see Activity::getHeartbeatDetails()
      *
      * @param Type|string $type
@@ -47,13 +55,17 @@ public function hasHeartbeatDetails(): bool;
     public function getHeartbeatDetails($type = null);
 
     /**
+     * Marks the activity as incomplete for asynchronous completion.
+     *
      * @see Activity::doNotCompleteOnReturn()
      *
      * @return void
      */
     public function doNotCompleteOnReturn(): void;
 
     /**
+     * Use to notify workflow that activity execution is alive.
+     *
      * @see Activity::heartbeat()
      *
      * @param mixed $details

diff --git a/src/Activity/ActivityInfo.php b/src/Activity/ActivityInfo.php
@@ -34,8 +34,9 @@
 final class ActivityInfo
 {
     /**
-     * A correlation token that can be used to complete the activity
-     * through {@see ActivityCompletionClientInterface::complete()}.
+     * A correlation token that can be used to complete the activity through `complete` method.
+     *
+     * @see ActivityCompletionClientInterface::complete()
      *
      * @var string
      */
@@ -62,7 +63,9 @@ final class ActivityInfo
 
     /**
      * An ID of the activity. This identifier can be used to complete the
-     * activity through {@see ActivityCompletionClientInterface::complete()}.
+     * activity through `complete` method.
+     *
+     * @see ActivityCompletionClientInterface::complete()
      *
      * @var string
      */

diff --git a/src/Activity/ActivityInterface.php b/src/Activity/ActivityInterface.php
@@ -16,10 +16,10 @@
 use Spiral\Attributes\NamedArgumentConstructor;
 
 /**
- * Indicates that an interface is an activity interface. Only interfaces
- * annotated with this annotation can be used as parameters
- * to {@see Workflow::activity()}
- * and {@see WorkflowContextInterface::newActivityStub()} methods.
+ * Indicates that an interface is an activity interface.
+ *
+ * Only interfaces annotated with this annotation can be used as parameters
+ * to {@see Workflow::activity()} and {@see WorkflowContextInterface::newActivityStub()} methods.
  *
  * Each method of the interface annotated with {@see ActivityInterface}
  * including inherited from interfaces is a separate activity. By default the

diff --git a/src/Activity/ActivityOptions.php b/src/Activity/ActivityOptions.php
@@ -24,9 +24,10 @@
 
 /**
  * ActivityOptions stores all activity-specific parameters that will be stored
- * inside of a context. The current timeout resolution implementation is in
- * seconds and uses `ceil($interval->s)` as the duration. But is subjected to
- * change in the future.
+ * inside of a context.
+ *
+ * The current timeout resolution implementation is in seconds and uses `ceil($interval->s)` as the duration.
+ * But is subjected to change in the future.
  *
  * @psalm-import-type DateIntervalValue from DateInterval
  */
@@ -64,8 +65,8 @@ class ActivityOptions extends Options implements ActivityOptionsInterface
     public \DateInterval $startToCloseTimeout;
 
     /**
-     * The periodic timeout while the activity is in execution. This is the max
-     * interval the server needs to hear at-least one ping from the activity.
+     * The periodic timeout while the activity is in execution.
+     * This is the max interval the server needs to hear at-least one ping from the activity.
      */
     #[Marshal(name: 'HeartbeatTimeout', type: DateIntervalType::class)]
     public \DateInterval $heartbeatTimeout;
@@ -81,15 +82,17 @@ class ActivityOptions extends Options implements ActivityOptionsInterface
 
     /**
      * Business level activity ID, this is not needed for most of the cases if
-     * you have to specify this then talk to temporal team. This is something
-     * will be done in future.
+     * you have to specify this then talk to temporal team.
+     *
+     * This is something will be done in the future.
      */
     #[Marshal(name: 'ActivityID')]
     public string $activityId = '';
 
     /**
-     * RetryPolicy specifies how to retry an Activity if an error occurs. More
-     * details are available at {@link https://docs.temporal.io/docs/concepts/activities}. RetryPolicy
+     * RetryPolicy specifies how to retry an Activity if an error occurs.
+     *
+     * More details are available at {@link https://docs.temporal.io/docs/concepts/activities}. RetryPolicy
      * is optional. If one is not specified a default RetryPolicy is provided
      * by the server.
      *
@@ -134,8 +137,9 @@ public function mergeWith(MethodRetry $retry = null): self
     }
 
     /**
-     * Task queue to use when dispatching activity task to a worker. By default
-     * it is the same task list name the workflow was started with.
+     * Task queue to use when dispatching activity task to a worker.
+     *
+     * By default, it is the same task list name the workflow was started with.
      *
      * @param string|null $taskQueue
      * @return $this
@@ -152,6 +156,7 @@ public function withTaskQueue(?string $taskQueue): self
 
     /**
      * Overall timeout workflow is willing to wait for activity to complete.
+     *
      * It includes time in a task queue:
      *
      * - Use {@see ActivityOptions::withScheduleToStartTimeout($timeout)} to limit it.
@@ -182,6 +187,7 @@ public function withScheduleToCloseTimeout($timeout): self
 
     /**
      * Time activity can stay in task queue before it is picked up by a worker.
+     *
      * If schedule to close is not provided then both this and start to close
      * are required.
      *
@@ -203,9 +209,9 @@ public function withScheduleToStartTimeout($timeout): self
     }
 
     /**
-     * Maximum activity execution time after it was sent to a worker. If
-     * schedule to close is not provided then both this and schedule to start
-     * are required.
+     * Maximum activity execution time after it was sent to a worker.
+     *
+     * If schedule to close is not provided then both this and schedule to start are required.
      *
      * @psalm-suppress ImpureMethodCall
      *
@@ -225,8 +231,9 @@ public function withStartToCloseTimeout($timeout): self
     }
 
     /**
-     * Heartbeat interval. Activity must heartbeat before this interval passes
-     * after a last heartbeat or activity start.
+     * Heartbeat interval.
+     *
+     * Activity must heartbeat before this interval passes after a last heartbeat or activity start.
      *
      * @psalm-suppress ImpureMethodCall
      *

diff --git a/src/Activity/LocalActivityInterface.php b/src/Activity/LocalActivityInterface.php
@@ -16,9 +16,9 @@
 use Spiral\Attributes\NamedArgumentConstructor;
 
 /**
- * Indicates that an interface is a local activity interface. Only interfaces
- * annotated with this annotation can be used as parameters
- * to {@see Workflow::activity()}
+ * Indicates that an interface is a local activity interface.
+ *
+ * Only interfaces annotated with this annotation can be used as parameters to {@see Workflow::activity()}
  * and {@see WorkflowContextInterface::newActivityStub()} methods.
  *
  * Each method of the interface annotated with {@see LocalActivityInterface}

diff --git a/src/Activity/LocalActivityOptions.php b/src/Activity/LocalActivityOptions.php
@@ -23,9 +23,10 @@
 
 /**
  * LocalActivityOptions stores all local activity-specific parameters that will be stored
- * inside of a context. The current timeout resolution implementation is in
- * seconds and uses `ceil($interval->s)` as the duration. But is subjected to
- * change in the future.
+ * inside of a context.
+ *
+ * The current timeout resolution implementation is in seconds and uses `ceil($interval->s)` as the duration.
+ * But is subjected to change in the future.
  *
  * @psalm-import-type DateIntervalValue from DateInterval
  */
@@ -48,8 +49,9 @@ class LocalActivityOptions extends Options implements ActivityOptionsInterface
     public \DateInterval $startToCloseTimeout;
 
     /**
-     * RetryPolicy specifies how to retry an Activity if an error occurs. More
-     * details are available at {@link https://docs.temporal.io/docs/concepts/activities}. RetryPolicy
+     * RetryPolicy specifies how to retry an Activity if an error occurs.
+     *
+     * More details are available at {@link https://docs.temporal.io/docs/concepts/activities}. RetryPolicy
      * is optional. If one is not specified a default RetryPolicy is provided
      * by the server.
      *