Merge pull request #33 from php-http/phpdoc-revert

revert generic annotations

.github/workflows/tests.yml

@@ -69,6 +69,9 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@v3
 
+      - name: Remove phpspec
+        run: composer remove --dev friends-of-phpspec/phpspec-code-coverage phpspec/phpspec
+
       - name: PHPStan
         uses: OskarStark/phpstan-ga@0.12.32
         env:

CHANGELOG.md

 # Change Log
 
-## 1.2.1
+## 1.3.0 - 2024-01-04
 
-### Added - 2023-11-08
+### Fixed
+
+- Reverted generic annotations on promise - as `then` returns another promise, there seems no way to properly document this.
+
+## 1.2.1 - 2023-11-08
+
+### Added
 
 - Fixed PHPDoc for `wait()` and `then()`'s `onRejected` callable
 

src/FulfilledPromise.php

@@ -6,29 +6,22 @@ namespace Http\Promise;
  * A promise already fulfilled.
  *
  * @author Joel Wurtz <joel.wurtz@gmail.com>
- *
- * @template-covariant T
- *
- * @implements Promise<T>
  */
 final class FulfilledPromise implements Promise
 {
     /**
-     * @var T
+     * @var mixed
      */
     private $result;
 
     /**
-     * @param T $result
+     * @param mixed $result
      */
     public function __construct($result)
     {
         $this->result = $result;
     }
 
-    /**
-     * {@inheritdoc}
-     */
     public function then(callable $onFulfilled = null, callable $onRejected = null)
     {
         if (null === $onFulfilled) {
@@ -42,23 +35,17 @@ final class FulfilledPromise implements Promise
         }
     }
 
-    /**
-     * {@inheritdoc}
-     */
     public function getState()
     {
         return Promise::FULFILLED;
     }
 
-    /**
-     * {@inheritdoc}
-     */
     public function wait($unwrap = true)
     {
         if ($unwrap) {
             return $this->result;
         }
 
-        return;
+        return null;
     }
 }

src/Promise.php

@@ -12,8 +12,6 @@ namespace Http\Promise;
  *
  * @author Joel Wurtz <joel.wurtz@gmail.com>
  * @author Márk Sági-Kazár <mark.sagikazar@gmail.com>
- *
- * @template-covariant T
  */
 interface Promise
 {
@@ -38,12 +36,10 @@ interface Promise
      * If you do not care about one of the cases, you can set the corresponding callable to null
      * The callback will be called when the value arrived and never more than once.
      *
-     * @param callable(T): V|null          $onFulfilled called when a response will be available
-     * @param callable(\Throwable): V|null $onRejected  called when an exception occurs
-     *
-     * @return Promise<V> a new resolved promise with value of the executed callback (onFulfilled / onRejected)
+     * @param callable|null $onFulfilled called when a response will be available
+     * @param callable|null $onRejected  called when an exception occurs
      *
-     * @template V
+     * @return Promise a new resolved promise with value of the executed callback (onFulfilled / onRejected)
      */
     public function then(callable $onFulfilled = null, callable $onRejected = null);
 
@@ -65,9 +61,9 @@ interface Promise
      *
      * @param bool $unwrap Whether to return resolved value / throw reason or not
      *
-     * @return ($unwrap is true ? T : null) Resolved value, null if $unwrap is set to false
+     * @return ($unwrap is true ? mixed : null) Resolved value, null if $unwrap is set to false
      *
-     * @throws \Exception the rejection reason if $unwrap is set to true and the request failed
+     * @throws \Throwable the rejection reason if $unwrap is set to true and the request failed
      */
     public function wait($unwrap = true);
 }

src/RejectedPromise.php

@@ -6,26 +6,19 @@ namespace Http\Promise;
  * A rejected promise.
  *
  * @author Joel Wurtz <joel.wurtz@gmail.com>
- *
- * @template-covariant T
- *
- * @implements Promise<T>
  */
 final class RejectedPromise implements Promise
 {
     /**
-     * @var \Exception
+     * @var \Throwable
      */
     private $exception;
 
-    public function __construct(\Exception $exception)
+    public function __construct(\Throwable $exception)
     {
         $this->exception = $exception;
     }
 
-    /**
-     * {@inheritdoc}
-     */
     public function then(callable $onFulfilled = null, callable $onRejected = null)
     {
         if (null === $onRejected) {
@@ -39,23 +32,17 @@ final class RejectedPromise implements Promise
         }
     }
 
-    /**
-     * {@inheritdoc}
-     */
     public function getState()
     {
         return Promise::REJECTED;
     }
 
-    /**
-     * {@inheritdoc}
-     */
     public function wait($unwrap = true)
     {
         if ($unwrap) {
             throw $this->exception;
         }
 
-        return;
+        return null;
     }
 }