improve and fix the documentation of the PERL_HASH function

diff --git a/pod/perlguts.pod b/pod/perlguts.pod
index 33bf007..215f518 100644 (file)
--- a/pod/perlguts.pod
+++ b/pod/perlguts.pod
@@ -462,15 +462,13 @@ by using the following:
 
 This returns NULL if the variable does not exist.
 
-The hash algorithm is defined in the C<PERL_HASH(hash, key, klen)> macro:
+The hash algorithm is defined in the C<PERL_HASH> macro:
 
-    hash = 0;
-    while (klen--)
-       hash = (hash * 33) + *key++;
-    hash = hash + (hash >> 5);                 /* after 5.6 */
+    PERL_HASH(hash, key, klen)
 
-The last step was added in version 5.6 to improve distribution of
-lower bits in the resulting hash value.
+The exact implementation of this macro varies by architecture and version
+of perl, and the return value may change per invocation, so the value
+is only valid for the duration of a single perl process.
 
 See L<Understanding the Magic of Tied Hashes and Arrays> for more
 information on how to use the hash access functions on tied hashes.