functions.xml Eliminate confusion in fn's parameters and arguments (#4062)

Author: mmalferov

language/functions.xml

@@ -5,7 +5,7 @@
 
   <sect1 xml:id="functions.user-defined">
    <title>User-defined functions</title>
- 
+
    <para>
     A function may be defined using syntax such as the following:
    </para>
@@ -168,14 +168,16 @@ function recursion($a)
    </para>
 
   </sect1>
- 
+
   <sect1 xml:id="functions.arguments">
-   <title>Function arguments</title>
- 
+   <title>Function parameters and arguments</title>
+
    <simpara>
+    The function parameters are declared in the function signature.
     Information may be passed to functions via the argument list,
     which is a comma-delimited list of expressions. The arguments are
-    evaluated from left to right, before the function is actually called
+    evaluated from left to right and the result is assigned to the parameters of
+    the function, before the function is actually called
     (<emphasis>eager</emphasis> evaluation).
    </simpara>
 
@@ -204,12 +206,12 @@ function takes_array($input)
     </example>
    </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.
+    As of PHP 8.0.0, the list of function parameters may include a trailing comma, which
+    will be ignored.  That is particularly useful in cases where the list of parameters is
+    long or contains long variable names, making it convenient to list parameters vertically.
    </para>
    <example>
-    <title>Function Argument List with trailing Comma</title>
+    <title>Function parameter list with trailing comma</title>
     <programlisting role="php">
 <![CDATA[
 <?php
@@ -230,7 +232,7 @@ function takes_many_args(
 
    <sect2 xml:id="functions.arguments.by-reference">
     <title>Passing arguments by reference</title>
- 
+
     <simpara>
      By default, function arguments are passed by value (so that if
      the value of the argument within the function is changed, it does
@@ -239,11 +241,11 @@ function takes_many_args(
     </simpara>
     <para>
      To have an argument to a function always passed by reference, prepend an
-     ampersand (&amp;) to the argument name in the function definition:
+     ampersand (&amp;) to the parameter name in the function definition:
     </para>
     <para>
      <example>
-      <title>Passing function parameters by reference</title>
+      <title>Passing function arguments by reference</title>
       <programlisting role="php">
 <![CDATA[
 <?php
@@ -260,16 +262,16 @@ echo $str;    // outputs 'This is a string, and something extra.'
      </example>
     </para>
     <para>
-     It is an error to pass a value as argument which is supposed to be passed by reference.
+     It is an error to pass a constant expression as argument to parameter that expects to be passed by reference.
     </para>
    </sect2>
    <sect2 xml:id="functions.arguments.default">
-    <title>Default argument values</title>
- 
+    <title>Default parameter values</title>
+
     <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; in particular, note that passing &null; does <emphasis>not</emphasis>
+     A function may define default values for parameters using syntax similar
+     to assigning a variable. The default is used only when the parameter's argument is
+     not passed. Note that passing &null; does <emphasis>not</emphasis>
      assign the default value.
     </para>
     <para>
@@ -367,21 +369,21 @@ Crafting a beautiful coffee just for you.
      example) a variable, a class member or a function call.
     </simpara>
     <para>
-     Note that any optional arguments should be specified after any
-     required arguments, otherwise they cannot be omitted from calls.
+     Note that any optional parameters should be specified after any
+     required parameters, otherwise they cannot be omitted from calls.
      Consider the following example:
     </para>
     <para>
      <example>
-      <title>Incorrect usage of default function arguments</title>
+      <title>Incorrect usage of default function parameters</title>
       <programlisting role="php">
 <![CDATA[
 <?php
 function makeyogurt($container = "bowl", $flavour)
 {
     return "Making a $container of $flavour yogurt.\n";
 }
- 
+
 echo makeyogurt("raspberry"); // "raspberry" is $container, not $flavour
 ?>
 ]]>
@@ -400,15 +402,15 @@ Fatal error: Uncaught ArgumentCountError: Too few arguments
     </para>
     <para>
      <example>
-      <title>Correct usage of default function arguments</title>
+      <title>Correct usage of default function parameters</title>
       <programlisting role="php">
 <![CDATA[
 <?php
 function makeyogurt($flavour, $container = "bowl")
 {
     return "Making a $container of $flavour yogurt.\n";
 }
- 
+
 echo makeyogurt("raspberry"); // "raspberry" is $flavour
 ?>
 ]]>
@@ -427,7 +429,7 @@ Making a bowl of raspberry yogurt.
     </para>
     <para>
      <example>
-      <title>Correct usage of default function arguments</title>
+      <title>Correct usage of default function parameters</title>
       <programlisting role="php">
 <![CDATA[
 <?php
@@ -449,16 +451,16 @@ Making a bowl of raspberry natural yogurt.
      </example>
     </para>
     <para>
-     As of PHP 8.0.0, declaring mandatory arguments after optional arguments
+     As of PHP 8.0.0, declaring mandatory parameters after optional parameters
      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
+     One exception to this rule are parameters of the form
      <code>Type $param = null</code>, where the &null; default makes the type implicitly
      nullable. This usage is deprecated as of PHP 8.4.0, and an explicit
      <link linkend="language.types.declarations.nullable">nullable type</link>
      should be used instead.
      <example>
-      <title>Declaring optional arguments after mandatory arguments</title>
+      <title>Declaring optional parameters after mandatory parameters</title>
       <programlisting role="php">
 <![CDATA[
 <?php
@@ -486,7 +488,7 @@ function bar(?A $a, $b) {}       // Recommended
     </note>
     <note>
      <simpara>
-      Arguments that are passed by reference may have a default value.
+      Parameters that expect the argument by reference may have a default value.
      </simpara>
     </note>
    </sect2>
@@ -501,7 +503,7 @@ function bar(?A $a, $b) {}       // Recommended
     </simpara>
 
     <para>
-     Argument lists may include the
+     Parameter lists may include the
      <literal>...</literal> token to denote that the function accepts a
      variable number of arguments. The arguments will be passed into the
      given variable as an &array;:
@@ -564,7 +566,7 @@ echo add(...$a);
     </para>
 
     <para>
-     You may specify normal positional arguments before the
+     You may specify normal positional parameters before the
      <literal>...</literal> token. In this case, only the trailing arguments
      that don't match a positional argument will be added to the array
      generated by <literal>...</literal>.
@@ -701,20 +703,24 @@ htmlspecialchars($string, ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401, 'UTF-8', fa
     </example>
 
     <para>
-     Passing the same parameter multiple times results in an Error exception.
+     Passing an argument to the same named parameter multiple times results in an
+     <classname>Error</classname> exception.
     </para>
 
     <example>
-     <title>Error thrown when passing the same parameter multiple times</title>
+     <title>Error thrown when passing an argument to the same named parameter multiple times</title>
      <programlisting role="php">
 <![CDATA[
 <?php
+
 function foo($param) { ... }
 
 foo(param: 1, param: 2);
 // Error: Named parameter $param overwrites previous argument
+
 foo(1, param: 2);
 // Error: Named parameter $param overwrites previous argument
+
 ?>
 ]]>
      </programlisting>
@@ -745,10 +751,10 @@ var_dump(foo(...[1, 2], b: 20)); // Fatal error. Named parameter $b overwrites p
 
    </sect2>
   </sect1>
- 
+
   <sect1 xml:id="functions.returning-values">
    <title>Returning values</title>
- 
+
    <para>
     Values are returned by using the optional return statement. Any
     type may be returned, including arrays and objects. This causes the
@@ -1463,7 +1469,7 @@ Warning: Cannot bind an instance to a static closure in %s on line %d
 <?php
 
 $y = 1;
- 
+
 $fn1 = fn($x) => $x + $y;
 // equivalent to using $y by value:
 $fn2 = function ($x) use ($y) {
@@ -1712,7 +1718,7 @@ $obj?->prop->method(...);
   </sect1>
 
  </chapter>
- 
+
 <!-- Keep this comment at the end of the file
 Local variables:
 mode: sgml