doc(async): add documentation

docs/README.md

@@ -4,10 +4,15 @@
     Any edits to it will likely be lost.
 -->
 
+# Components
+
+ * [Psl\Async](../src/Psl/Async/README.md)
+
+---
+
 # Components API
 
 - [Psl](./component/psl.md)
-- [Psl\Async](./component/async.md)
 - [Psl\Channel](./component/channel.md)
 - [Psl\Class](./component/class.md)
 - [Psl\Collection](./component/collection.md)

docs/documenter.php

@@ -186,7 +186,6 @@ function get_all_components(): array
 {
     $components = [
         'Psl',
-        'Psl\\Async',
         'Psl\\Channel',
         'Psl\\Class',
         'Psl\\Collection',

docs/templates/README.template.md

@@ -4,6 +4,12 @@
     Any edits to it will likely be lost.
 -->
 
+# Components
+
+ * [Psl\Async](../src/Psl/Async/README.md)
+
+---
+
 # Components API
 
 {{ list }}

src/Psl/Async/Awaitable.php

@@ -42,7 +42,7 @@ public function __construct(State $state)
     }
 
     /**
-     * Iterate over the given awaitables in completion order.
+     * Iterate over the given `Awaitable`s in completion order.
      *
      * @template Tk
      * @template Tv
@@ -125,7 +125,6 @@ public function isComplete(): bool
         return $this->state->isComplete();
     }
 
-
     /**
      * {@inheritDoc}
      *

src/Psl/Async/KeyedSemaphore.php

@@ -17,7 +17,8 @@
 /**
  * Run an operation with a limit on number of ongoing asynchronous jobs for a specific key.
  *
- * All operations must have the same input type (Tin) and output type (Tout), and be processed by the same function;
+ * All operations must have the same input type (Tin) and output type (Tout), and be processed by the same function.
+ *
  * `Tin` may be a callable invoked by the `$operation` for maximum flexibility,
  * however this pattern is best avoided in favor of creating semaphores with a more narrow process.
  *
@@ -47,15 +48,15 @@ final class KeyedSemaphore
      * @param (Closure(Tk, Tin): Tout) $operation
      */
     public function __construct(
-        private int $concurrencyLimit,
-        private Closure $operation,
+        private readonly int $concurrencyLimit,
+        private readonly Closure $operation,
     ) {
     }
 
     /**
      * Run the operation using the given `$input`.
      *
-     * If the concurrency limit has been reached, this method will wait until one of the ingoing operations has completed.
+     * If the concurrency limit has been reached for the given `$key`, this method will wait until one of the ingoing operations has completed.
      *
      * @param Tk $key
      * @param Tin $input

src/Psl/Async/KeyedSequence.php

@@ -45,7 +45,7 @@ final class KeyedSequence
      * @param (Closure(Tk, Tin): Tout) $operation
      */
     public function __construct(
-        private Closure $operation,
+        private readonly Closure $operation,
     ) {
     }