From 17726a33d9ce05da7a1cdd0c2679e97cbac7328e Mon Sep 17 00:00:00 2001
From: Jaapio <jaap@ijaap.nl>
Date: Fri, 17 Sep 2021 16:52:11 +0200
Subject: [PATCH 1/2] Add support for never keyword

php 8.1 introduces the `never` keyword, which can be used as return type.
---
 src/TypeResolver.php            |  1 +
 src/Types/Never_.php            | 35 +++++++++++++++++++++++++++++++++
 tests/unit/TypeResolverTest.php |  1 +
 3 files changed, 37 insertions(+)
 create mode 100644 src/Types/Never_.php

diff --git a/src/TypeResolver.php b/src/TypeResolver.php
index 47d6f16..79c079b 100644
--- a/src/TypeResolver.php
+++ b/src/TypeResolver.php
@@ -107,6 +107,7 @@ final class TypeResolver
         'static' => Types\Static_::class,
         'parent' => Types\Parent_::class,
         'iterable' => Types\Iterable_::class,
+        'never' => Types\Never_::class,
     ];
 
     /**
diff --git a/src/Types/Never_.php b/src/Types/Never_.php
new file mode 100644
index 0000000..e5752eb
--- /dev/null
+++ b/src/Types/Never_.php
@@ -0,0 +1,35 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of phpDocumentor.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ *
+ * @link      http://phpdoc.org
+ */
+
+namespace phpDocumentor\Reflection\Types;
+
+use phpDocumentor\Reflection\Type;
+
+/**
+ * Value Object representing the pseudo-type 'never'.
+ *
+ * Never is generally only used when working with return types as it signifies that the method that only
+ * ever throw or exit.
+ *
+ * @psalm-immutable
+ */
+final class Never_ implements Type
+{
+    /**
+     * Returns a rendered output of the Type as it would be used in a DocBlock.
+     */
+    public function __toString(): string
+    {
+        return 'never';
+    }
+}
diff --git a/tests/unit/TypeResolverTest.php b/tests/unit/TypeResolverTest.php
index 2b16e93..500cccf 100644
--- a/tests/unit/TypeResolverTest.php
+++ b/tests/unit/TypeResolverTest.php
@@ -757,6 +757,7 @@ public function provideKeywords(): array
             ['self', Types\Self_::class],
             ['parent', Types\Parent_::class],
             ['iterable', Types\Iterable_::class],
+            ['never', Types\Never_::class],
         ];
     }
 

From 4d427faba4583d244def085610e39f90fe5a4f3e Mon Sep 17 00:00:00 2001
From: Jaapio <jaap@ijaap.nl>
Date: Fri, 17 Sep 2021 17:20:15 +0200
Subject: [PATCH 2/2] Improve docs about return only types

Void and never are types that can only be used for function return
types. Officially php doesn't have a category of types that are only
allowed for return, but I think it makes sense to name them like this.
---
 src/Types/Never_.php | 2 +-
 src/Types/Void_.php  | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/Types/Never_.php b/src/Types/Never_.php
index e5752eb..40a99c9 100644
--- a/src/Types/Never_.php
+++ b/src/Types/Never_.php
@@ -16,7 +16,7 @@
 use phpDocumentor\Reflection\Type;
 
 /**
- * Value Object representing the pseudo-type 'never'.
+ * Value Object representing the return-type 'never'.
  *
  * Never is generally only used when working with return types as it signifies that the method that only
  * ever throw or exit.
diff --git a/src/Types/Void_.php b/src/Types/Void_.php
index 3836bdc..23a601d 100644
--- a/src/Types/Void_.php
+++ b/src/Types/Void_.php
@@ -16,7 +16,7 @@
 use phpDocumentor\Reflection\Type;
 
 /**
- * Value Object representing the pseudo-type 'void'.
+ * Value Object representing the return-type 'void'.
  *
  * Void is generally only used when working with return types as it signifies that the method intentionally does not
  * return any value.