Style improvements, and a couple of extra notes.

appendices/migration81/incompatible.xml

@@ -63,8 +63,10 @@ var_dump(B::counter()); // int(4), previously int(2)
     specified before required parameters is now always treated as required,
     even when called using
     <link linkend="functions.named-arguments">named arguments</link>.
-    In PHP 8.0, the below emits a deprecation notice on the definition,
-    but runs successfully when called. As of PHP 8.1, an error is thrown.
+    As of PHP 8.0.0, but prior to PHP 8.1.0, the below emits a deprecation notice
+    on the definition, but runs successfully when called. As of PHP 8.1.0, an error
+    of class <classname>ArgumentCountError</classname> is thrown, as it would be when
+    called with positional arguments.
 
     <informalexample>
      <programlisting role="php">
@@ -87,7 +89,7 @@ catch (Error $e)
      </programlisting>
      &example.outputs.80;
      <screen>
-      <![CDATA[
+<![CDATA[
 Deprecated: Required parameter $flavour follows optional parameter $container
  in example.php on line 3
 Making a bowl of raspberry yogurt.
@@ -102,7 +104,11 @@ ArgumentCountError - makeyogurt(): Argument #1 ($container) not passed
 ]]>
      </screen>
     </informalexample>
-
+   </para>
+   <para>
+    Note that a default value of &null; can be used before required parameters to
+    specify a <link linkend="language.types.declarations.nullable">nullable type</link>,
+    but the parameter will still be required.
    </para>
   </sect3>
 

language/functions.xml

@@ -224,28 +224,6 @@ function takes_many_args(
     // ...
 }
 ?>
-]]>
-    </programlisting>
-   </example>
-   <para>
-    As of PHP 8.0.0, declaring mandatory arguments after optional arguments
-    is deprecated. This can generally be resolved by dropping the default value.
-    One exception to this rule are arguments of the form
-    <code>Type $param = null</code>, where the &null; default makes the type implicitly
-    nullable. This usage remains allowed, though it is recommended to use an
-    explicit nullable type instead.
-   </para>
-   <example>
-    <title>Declaring optional arguments after mandatory arguments</title>
-    <programlisting role="php">
-<![CDATA[
-<?php
-function foo($a = [], $b) {} // Before
-function foo($a, $b) {}      // After
-
-function bar(A $a = null, $b) {} // Still allowed
-function bar(?A $a, $b) {}       // Recommended
-?>
 ]]>
     </programlisting>
    </example>
@@ -291,7 +269,8 @@ echo $str;    // outputs 'This is a string, and something extra.'
     <para>
      A function may define default values for arguments using syntax similar
      to assigning a variable. The default is used only when the parameter is
-     not specified.
+     not specified; in particular, note that passing &null; does <emphasis>not</emphasis>
+     assign the default value.
     </para>
     <para>
      <example>
@@ -321,7 +300,7 @@ Making a cup of espresso.
     </para>
     <para>
      Default parameter values may be scalar values, <type>array</type>s,
-     the special type &null;, and as of PHP 8.1, objects using the
+     the special type &null;, and as of PHP 8.1.0, objects using the
      <link linkend="language.oop5.basic.new">new ClassName()</link> syntax.
     </para>
     <para>
@@ -343,7 +322,7 @@ echo makecoffee(array("cappuccino", "lavazza"), "teapot");?>
     </para>
     <para>
      <example>
-      <title>Using objects as default values (as of PHP 8.1)</title>
+      <title>Using objects as default values (as of PHP 8.1.0)</title>
       <programlisting role="php">
 <![CDATA[
 <?php
@@ -428,7 +407,7 @@ Making a bowl of raspberry yogurt.
      </example>
     </para>
     <para>
-     As of PHP 8.0, <link linkend="functions.named-arguments">named arguments</link>
+     As of PHP 8.0.0, <link linkend="functions.named-arguments">named arguments</link>
      can be used to skip over multiple optional parameters.
     </para>
     <para>
@@ -454,17 +433,35 @@ Making a bowl of raspberry natural yogurt.
       </screen>
      </example>
     </para>
+    <para>
+     As of PHP 8.0.0, declaring mandatory arguments after optional arguments
+     is <emphasis>deprecated</emphasis>. This can generally be resolved by
+     dropping the default value, since it will never be used.
+     One exception to this rule are arguments of the form
+     <code>Type $param = null</code>, where the &null; default makes the type implicitly
+     nullable. This usage remains allowed, though it is recommended to use an
+     explicit <link linkend="language.types.declarations.nullable">nullable type</link> instead.
+     <example>
+      <title>Declaring optional arguments after mandatory arguments</title>
+      <programlisting role="php">
+<![CDATA[
+ <?php
+ function foo($a = [], $b) {} // Default not used; deprecated as of PHP 8.0.0
+ function foo($a, $b) {}      // Functionally equivalent, no deprecation notice
+
+ function bar(A $a = null, $b) {} // Still allowed; $a is required but nullable
+ function bar(?A $a, $b) {}       // Recommended
+ ?>
+ ]]>
+      </programlisting>
+     </example>
+    </para>
     <note>
      <simpara>
-      As of PHP 7.1, omitting a parameter which does not specify a default
+      As of PHP 7.1.0, omitting a parameter which does not specify a default
       throws an <classname>ArgumentCountError</classname>; in previous versions
       it raised a Warning.
      </simpara>
-     <simpara>
-      As of PHP 8.0, <emphasis>defining</emphasis> a function with optional
-      parameters after required parameters (as in the first "yogurt"
-      example above) is DEPRECATED.
-     </simpara>
     </note>
     <note>
      <simpara>
@@ -671,7 +668,7 @@ echo sum(1, 2, 3, 4);
     <example>
      <title>Named argument syntax</title>
      <programlisting role="php">
-      <![CDATA[
+<![CDATA[
 <?php
 myFunction(paramName: $value);
 array_foobar(array: $value);
@@ -686,7 +683,7 @@ function_name($variableStoringParamName: $value);
     <example>
      <title>Positional arguments versus named arguments</title>
      <programlisting role="php">
-      <![CDATA[
+<![CDATA[
 <?php
 // Using positional arguments:
 array_fill(0, 100, 50);
@@ -705,7 +702,7 @@ array_fill(start_index: 0, count: 100, value: 50);
     <example>
      <title>Same example as above with a different order of parameters</title>
      <programlisting role="php">
-      <![CDATA[
+<![CDATA[
 <?php
 array_fill(value: 50, count: 100, start_index: 0);
 ?>
@@ -723,7 +720,7 @@ array_fill(value: 50, count: 100, start_index: 0);
     <example>
      <title>Combining named arguments with positional arguments</title>
      <programlisting role="php">
-      <![CDATA[
+<![CDATA[
 <?php
 htmlspecialchars($string, double_encode: false);
 // Same as
@@ -738,9 +735,9 @@ htmlspecialchars($string, ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401, 'UTF-8', fa
     </para>
 
     <example>
-     <title>Error exception when passing the same parameter multiple times</title>
+     <title>Error thrown when passing the same parameter multiple times</title>
      <programlisting role="php">
-      <![CDATA[
+<![CDATA[
 <?php
 function foo($param) { ... }