Merge pull request #3149 from ntrel/noreturn

[spec] Document `noreturn`

Signed-off-by: Dennis <dkorpel@users.noreply.github.com>
Merged-on-behalf-of: Dennis <dkorpel@users.noreply.github.com>

Author: dlang-bot

spec/importc.dd

@@ -255,8 +255,8 @@ $(H2 $(LNAME2 gnu-clang-extensions, Gnu and Clang Extensions))
     $(P `__attribute__((noreturn))` marks a function as never returning.
     `gcc` set this as an attribute of the function, it is
     not part of the function's type. In D, a function that never returns
-    has the return type `noreturn`. The difference can be seen with the
-    code:)
+    has the return type $(GLINK2 type, noreturn). The difference can be
+    seen with the code:)
     $(CCODE
     attribute((noreturn)) int foo();
     size_t x = sizeof(foo());

spec/type.dd

@@ -558,6 +558,37 @@ $(H3 $(LNAME2 string, $(D string)))
 
     $(P A $(DDSUBLINK spec/arrays, strings, $(I string) is a special case of an array.))
 
+$(H3 $(LNAME2 noreturn, $(D noreturn)))
+
+    $(P `noreturn` is the $(LINK2 https://en.wikipedia.org/wiki/Bottom_type, bottom type)
+    which can implicitly convert to any type, including `void`.
+    A value of type `noreturn` will never be produced and the compiler can
+    optimize such code accordingly.)
+
+    $(P A function that never returns has the return type `noreturn`. This can
+    occur due to an infinite loop or always throwing an exception.)
+
+$(SPEC_RUNNABLE_EXAMPLE_COMPILE
+---
+noreturn abort(const(char)[] message);
+
+int example(int i)
+{
+    if (i < 0)
+    {
+        // abort does not return, so it doesn't need to produce an int
+        int val = abort("less than zero");
+    }
+    // ternary expression's common type is still int
+    return i != 0 ? 1024 / i : abort("calculation went awry.");
+}
+---
+)
+
+    $(P `noreturn` is defined as $(D typeof(*null)). This is because
+    dereferencing a null literal halts execution.)
+
+
 $(SPEC_SUBNAV_PREV_NEXT declaration, Declarations, property, Properties)
 )