From 975e9114e8aaf86762bce636d589eb043e72ccb6 Mon Sep 17 00:00:00 2001
From: George Peter Banyard <girgias@php.net>
Date: Thu, 23 Sep 2021 13:59:21 +0100
Subject: [PATCH] Add documentation about the never type (#889)

---
 language/types/declarations.xml | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/language/types/declarations.xml b/language/types/declarations.xml
index 8933dba294..0d7dd56bed 100644
--- a/language/types/declarations.xml
+++ b/language/types/declarations.xml
@@ -513,6 +513,22 @@ function foo(): X|Y {} // Allowed (redundancy is only known at runtime)
    </para>
   </sect3>
 
+  <sect3 xml:id="language.types.declarations.never">
+   <title>never</title>
+   <para>
+    <literal>never</literal> is a return type indicating the function does not
+    return. This means that it either calls <function>exit</function>, throws
+    an exception, or is an infinite loop.
+    Therefore it cannot be part of a union type declaration.
+    Available as of PHP 8.1.0.
+   </para>
+   <para>
+    <type>never</type> is, in type theory parlance, the bottom type.
+    Meaning it is the subtype of every other type and can replace any other
+    return type during inheritance.
+   </para>
+  </sect3>
+
   <sect3 xml:id="language.types.declarations.static">
    <title>static</title>
    <para>