From 574f492ae951e820d36bc6d9273f9da90ba46ef7 Mon Sep 17 00:00:00 2001
From: Christoph Michael Becker <cmb@php.net>
Date: Sat, 28 Nov 2020 22:43:21 +0000
Subject: [PATCH] Function trailing commas

* Trailing commas in function parameter list.
* Trailing commas in use clause.
* Minor language change along the way.

Closes GH-241.


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

diff --git a/language/functions.xml b/language/functions.xml
index 7e7ee0513c..6bc703776d 100644
--- a/language/functions.xml
+++ b/language/functions.xml
@@ -200,7 +200,31 @@ function takes_array($input)
 ]]>
      </programlisting>
     </example>
-   </para>   
+   </para>
+   <para>
+    As of PHP 8.0.0, the list of function arguments may include a trailing comma, which
+    will be ignored.  That is particularly useful in cases where the list of arguments is
+    long or contains long variable names, making it convenient to list arguments vertically.
+   </para>
+   <example>
+    <title>Function Argument List with trailing Comma</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+function takes_many_args(
+    $first_arg,
+    $second_arg,
+    $a_very_long_argument_name,
+    $arg_with_default = 5,
+    $again = 'a default string', // This trailing comma was not permitted before 8.0.0.
+)
+{
+    // ...
+}
+?>
+]]>
+    </programlisting>
+   </example>
    <sect2 xml:id="functions.arguments.by-reference">
     <title>Passing arguments by reference</title>
  
@@ -885,7 +909,7 @@ $greet('PHP');
    <simpara>
     Closures may also inherit variables from the parent scope. Any such
     variables must be passed to the <literal>use</literal> language construct.
-    From PHP 7.1, these variables must not include &link.superglobals;,
+    As of PHP 7.1, these variables must not include &link.superglobals;,
     <varname>$this</varname>, or variables with the same name as a parameter.
    </simpara>
 
@@ -949,6 +973,10 @@ string(11) "hello world"
     </screen>
    </example>
 
+   <para>
+    As of PHP 8.0.0, the list of scope-inherited variables may include a trailing
+    comma, which will be ignored.
+   </para>
    <simpara>
     Inheriting variables from the parent scope is <emphasis>not</emphasis> 
     the same as using global variables.