Update documentation for hash_combine.

Also added some disclaimers for anyone who didn't notice the note in the
introduction.

hash/doc/changes.qbk

@@ -171,6 +171,7 @@
 [h2 Boost 1.56.0]
 
 * Removed some Visual C++ 6 workarounds.
-* Ongoing work on improving `hash_combine`.
+* Ongoing work on improving `hash_combine`. This changes the combine function
+  which was previously defined in the reference documentation.
 
 [endsect]

hash/doc/ref.xml

@@ -59,6 +59,11 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
               Forward declared in
               <code>&lt;boost/functional/hash_fwd.hpp&gt;</code>
             </para>
+            <para>
+              This hash function is not intended for general use, and isn't
+              guaranteed to be equal during separate runs of a program - so
+              please don't use it for any persistent storage or communication.
+            </para>
           </notes>
           <throws><para>
             Only throws if
@@ -450,7 +455,15 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
             Called repeatedly to incrementally create a hash value from
             several variables.
         </simpara></purpose>
-        <effects><programlisting>seed ^= <functionname>hash_value</functionname>(v) + 0x9e3779b9 + (seed &lt;&lt; 6) + (seed &gt;&gt; 2);</programlisting></effects>
+        <effects>
+            Updates <code>seed</code> with a new hash value generated by
+            combining it with the result of
+            <code><functionname>hash_value</functionname>(v)</code>. Will
+            always produce the same result for the same combination of
+            <code>seed</code> and
+            <code><functionname>hash_value</functionname>(v)</code> during
+            the single run of a program.
+        </effects>
         <notes>
           <para><functionname>hash_value</functionname> is called without
           qualification, so that overloads can be found via ADL.</para>
@@ -459,6 +472,11 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
             Forward declared in
             <code>&lt;boost/functional/hash_fwd.hpp&gt;</code>
           </para>
+          <para>
+            This hash function is not intended for general use, and isn't
+            guaranteed to be equal during separate runs of a program - so
+            please don't use it for any persistent storage or communication.
+          </para>
         </notes>
         <throws>
           Only throws if <functionname>hash_value</functionname>(T) throws.
@@ -527,6 +545,11 @@ for(; first != last; ++first)
             Forward declared in
             <code>&lt;boost/functional/hash_fwd.hpp&gt;</code>
           </para>
+          <para>
+            This hash function is not intended for general use, and isn't
+            guaranteed to be equal during separate runs of a program - so
+            please don't use it for any persistent storage or communication.
+          </para>
         </notes>
         <throws><para>
           Only throws if <code><functionname>hash_value</functionname>(std::iterator_traits&lt;It&gt;::value_type)</code>
@@ -784,6 +807,11 @@ for(; first != last; ++first)
 
         <notes>
           <para>This is an extension to TR1</para>
+          <para>
+            This hash function is not intended for general use, and isn't
+            guaranteed to be equal during separate runs of a program - so
+            please don't use it for any persistent storage or communication.
+          </para>
         </notes>
 
         <throws>