Add more details about WeakReferences (#3976)

Possible follow-up is to describe weak references in more details elsewhere in the manual.

Co-authored-by: Jim Winstead <[email protected]>
Co-authored-by: Gina Peter Banyard <[email protected]>

Author: 3 people

language/predefined/weakreference.xml

@@ -13,6 +13,11 @@
    <para>
     Weak references allow the programmer to retain a reference to an object which does not prevent
     the object from being destroyed. They are useful for implementing cache like structures.
+    If the original object has been destroyed, &null; will be returned
+    when calling the <methodname>WeakReference::get</methodname> method.
+    The original object will be destroyed when the
+    <link linkend="features.gc.refcounting-basics">refcount</link> for it drops to zero;
+    creating weak references does not increase the <literal>refcount</literal> of the object being referenced.
    </para>
    <para>
     <classname>WeakReference</classname>s cannot be serialized.
@@ -50,11 +55,16 @@
      <programlisting role="php">
 <![CDATA[
 <?php
-$obj = new stdClass;
+
+$obj = new stdClass();
 $weakref = WeakReference::create($obj);
+
 var_dump($weakref->get());
+
 unset($obj);
+
 var_dump($weakref->get());
+
 ?>
 ]]>
      </programlisting>