diff --git a/language/functions.xml b/language/functions.xml
index 2d4fb6c9f4..8f39f34cc0 100644
--- a/language/functions.xml
+++ b/language/functions.xml
@@ -366,8 +366,8 @@ Making a bowl of acidophilus raspberry.
     </note>
 
     <para>
-     Type declarations allow functions to require that parameters are of a
-     certain type at call time. If the given value is of the incorrect type,
+     Type declarations allow functions to specify parameters as certain types.
+     If the given value is of the incorrect type,
      then an error is generated: in PHP 5, this will be a recoverable fatal
      error, while PHP 7 will throw a <classname>TypeError</classname>
      exception.
@@ -453,6 +453,35 @@ Making a bowl of acidophilus raspberry.
        </tbody>
       </tgroup>
      </informaltable>
+
+     <warning>
+      <para>
+       Aliases for the above scalar types are not supported. Instead, they are
+       treated as class or interface names. For example, using
+       <literal>boolean</literal> as a parameter or return type will require
+       an argument or return value that is an &instanceof; the class or
+       interface <literal>boolean</literal>, rather than of type
+       <type>bool</type>:
+      </para>
+      <para>
+       <example>
+        <programlisting role="php">
+ <![CDATA[
+ <?php
+ function test(boolean $param) {}
+ test(true);
+ ?>
+ ]]>
+        </programlisting>
+        &example.outputs;
+        <screen>
+ <![CDATA[
+ Fatal error: Uncaught TypeError: Argument 1 passed to test() must be an instance of boolean, boolean given, called in - on line 1 and defined in -:1
+ ]]>
+        </screen>
+       </example>
+      </para>
+     </warning>
     </sect3>
 
     <sect3 xml:id="functions.arguments.type-declaration.examples">