From add41695ca84eecde2e3d2f3bae839e16add1ef7 Mon Sep 17 00:00:00 2001
From: Christoph Michael Becker <cmb@php.net>
Date: Mon, 26 Nov 2018 12:32:50 +0000
Subject: [PATCH] Document nullable return types

Based on a patch provided by Massimo Naccari.

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@346044 c90b9560-bf6c-de11-be94-00142212c4b1
---
 language/functions.xml | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/language/functions.xml b/language/functions.xml
index 73c1a19dfe..b193f901c3 100644
--- a/language/functions.xml
+++ b/language/functions.xml
@@ -1014,6 +1014,12 @@ $newref =& returns_reference();
     correct type, otherwise a <classname>TypeError</classname> will be thrown.
    </para>
 
+   <para>
+    As of PHP 7.1.0, return values can be marked as nullable by prefixing the
+    type name with a question mark (<literal>?</literal>). This signifies that
+    the function returns either the specified type or &null;.
+   </para>
+
    <note>
     <para>
      When overriding a parent method, the child's method must match any return
@@ -1100,6 +1106,23 @@ object(C)#1 (0) {
 ]]>
       </screen>
      </example>
+
+     <example>
+      <title>Nullable return type declaration (as of PHP 7.1.0)</title>
+      <programlisting role="php">
+<![CDATA[
+<?php
+function get_item(): ?string {
+    if (isset($_GET['item'])) {
+        return $_GET['item'];
+    } else {
+        return null;
+    }
+}
+?>
+]]>
+      </programlisting>
+     </example>
     </sect3>
    </sect2>
   </sect1>