From 8262c06d5f424363a68eb086a92171de9bf727c0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Gustavo=20Andr=C3=A9=20dos=20Santos=20Lopes?=
 <cataphract@php.net>
Date: Sat, 19 Nov 2011 17:36:18 +0000
Subject: [PATCH] Documentation for SplObjectStorage::getHash().

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@319549 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/spl/splobjectstorage/gethash.xml | 68 ++++++++++++++++++++--
 1 file changed, 62 insertions(+), 6 deletions(-)

diff --git a/reference/spl/splobjectstorage/gethash.xml b/reference/spl/splobjectstorage/gethash.xml
index bb73b661af..3be25f0fac 100644
--- a/reference/spl/splobjectstorage/gethash.xml
+++ b/reference/spl/splobjectstorage/gethash.xml
@@ -4,7 +4,9 @@
 <refentry xml:id="splobjectstorage.gethash" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>SplObjectStorage::getHash</refname>
-  <refpurpose>Returns the hash of an object</refpurpose>
+  <refpurpose>
+   Calculate an unique identifier for the contained objects
+  </refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
@@ -14,10 +16,20 @@
    <methodparam><type>string</type><parameter>object</parameter></methodparam>
   </methodsynopsis>
   <para>
-
+   The function calculates an identifier for the objects added to this
+   <classname>SplObjectStorage</classname> object.
+  </para>
+  <para>
+   The implementation in <classname>SplObjectStorage</classname> returns
+   the same value as <function>spl_object_hash</function>.
+  </para>
+  <para>
+   This identifer must unique among the objects contained. This means this
+   object will never contain more than one object with the same identifier.
+   As such, it can be used to implement a set (a collection of unique values)
+   where the quality of an object being unique is determined by the value
+   returned by this function being unique.
   </para>
-
-  &warn.undocumented.func;
 
  </refsect1>
 
@@ -28,7 +40,7 @@
     <term><parameter>object</parameter></term>
     <listitem>
      <para>
-      
+      The object whose identifier is to be calculated.
      </para>
     </listitem>
    </varlistentry>
@@ -38,10 +50,54 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-
+   A <type>string</type> with the calculated identifier. An exception is
+   thrown if any other type is returned.
   </para>
  </refsect1>
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example>
+    <title><function>SplObjectStorage::getHash</function> example</title>
+<programlisting role="php">
+<![CDATA[
+<?php
+class OneSpecimenPerClassStorage extends SplObjectStorage {
+            public function getHash($o) {
+                            return get_class($o);
+                                }
+}
+class A {}
 
+$s = new OneSpecimenPerClassStorage;
+$o1 = new stdclass;
+$o2 = new stdclass;
+$o3 = new A;
+
+$s[$o1] = 1;
+//$o2 is considered equal to $o1 so the value is replaced
+$s[$o2] = 2;
+$s[$o3] = 3;
+
+//these are considered equal to the objects before
+//so they can be used to access the values stored under them
+$p1 = new stdclass;
+$p2 = new A;
+echo $s[$p1], "\n";
+echo $s[$p2], "\n";
+?>
+]]>
+    </programlisting>
+    &example.outputs.similar;
+    <screen>
+<![CDATA[
+2
+3
+]]>
+    </screen>
+   </example>
+  </para>
+ </refsect1>
 
 </refentry>