From 337409a8c5184f3351fe7acc71c391b28ca2553d Mon Sep 17 00:00:00 2001
From: Jakub Vrana <vrana@php.net>
Date: Mon, 12 Mar 2012 05:06:15 +0000
Subject: [PATCH] Omissions and best practices

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@324121 c90b9560-bf6c-de11-be94-00142212c4b1
---
 language/types/array.xml        | 25 +++++++++++++++++++++----
 language/types/pseudo-types.xml |  2 ++
 2 files changed, 23 insertions(+), 4 deletions(-)

diff --git a/language/types/array.xml b/language/types/array.xml
index f80b6019d6..4b5a4cf6a6 100644
--- a/language/types/array.xml
+++ b/language/types/array.xml
@@ -41,6 +41,13 @@ array(
 )</synopsis>
    <!-- Do not fix the whitespace for the synopsis end element. A limitation of PhD prevents proper trimming -->
 
+   <para>
+    It is possible to write a comma after last element or omit it. Result is
+    the same, <literal>array(1, 2) === array(1, 2,)</literal>. Writing comma
+    after last element is useful mainly when formatting array definition on
+    multiple lines (see next example).
+   </para>
+   
    <para>
     As of PHP 5.4 you can also use the short array syntax, which replaces
     <literal>array()</literal> with <literal>[]</literal>.
@@ -53,13 +60,13 @@ array(
 <?php
 $array = array(
     "foo" => "bar",
-    "bar" => "foo"
+    "bar" => "foo",
 );
 
 // as of PHP 5.4
 $array = [
     "foo" => "bar",
-    "bar" => "foo"
+    "bar" => "foo",
 ];
 ?>
 ]]>
@@ -356,7 +363,17 @@ $arr[] = <replaceable>value</replaceable>;
    
    <para>
     If <varname>$arr</varname> doesn't exist yet, it will be created, so this is
-    also an alternative way to create an <type>array</type>. To change a certain
+    also an alternative way to create an <type>array</type>. This practice is
+    however discouraged because if <varname>$arr</varname> already contains
+    some value (e.g. <type>string</type> from request variable) then this
+    value will stay in the place and <literal>[]</literal> may actually stand
+    for <link linkend="language.types.string.substr">string access
+    operator</link>. It is always better to initialize variable by a direct
+    assignment.
+   </para>
+
+   <para>
+    To change a certain
     value, assign a new value to that element using its key. To remove a
     key/value pair, call the <function>unset</function> function on it.
    </para>
@@ -385,7 +402,7 @@ unset($arr);    // This deletes the whole array
     <para>
      As mentioned above, if no key is specified, the maximum of the existing
      <type>integer</type> indices is taken, and the new key will be that maximum
-     value plus 1. If no <type>integer</type> indices exist yet, the key will
+     value plus 1 (but at least 0). If no <type>integer</type> indices exist yet, the key will
      be <literal>0</literal> (zero). 
     </para>
 
diff --git a/language/types/pseudo-types.xml b/language/types/pseudo-types.xml
index 270a09b60f..3c87c2d3e9 100644
--- a/language/types/pseudo-types.xml
+++ b/language/types/pseudo-types.xml
@@ -59,6 +59,8 @@
    Static class methods can also be passed without instantiating an
    <type>object</type> of that class by passing the class name instead of an
    <type>object</type> at index 0.
+   As of PHP 5.2.3, it is also possible to pass
+   <literal>'ClassName::methodName'</literal>.
   </para>
 
   <para>