Hash: Add some notes about forwarding header. Refs #6849.

[SVN r78366]

hash/doc/ref.xml

@@ -55,6 +55,10 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
               is defined. The specializations are still defined, so only the specializations
               required by TR1 are defined.
             </para>
+            <para>
+              Forward declared in
+              <code>&lt;boost/functional/hash_fwd.hpp&gt;</code>
+            </para>
           </notes>
           <throws><para>
             Only throws if
@@ -451,6 +455,10 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
           <para><functionname>hash_value</functionname> is called without
           qualification, so that overloads can be found via ADL.</para>
           <para>This is an extension to TR1</para>
+          <para>
+            Forward declared in
+            <code>&lt;boost/functional/hash_fwd.hpp&gt;</code>
+          </para>
         </notes>
         <throws>
           Only throws if <functionname>hash_value</functionname>(T) throws.
@@ -499,15 +507,14 @@ for(; first != last; ++first)
 
 return seed;
 </programlisting>
-          </para>For the three arguments overload:
+          </para>
+          <para>For the three arguments overload:</para>
 <programlisting>
 for(; first != last; ++first)
 {
     <functionname>hash_combine</functionname>(seed, *first);
 }
 </programlisting>
-          <para>
-          </para>
         </effects>
         <notes>
           <para>
@@ -516,6 +523,10 @@ for(; first != last; ++first)
             container.
           </para>
           <para>This is an extension to TR1</para>
+          <para>
+            Forward declared in
+            <code>&lt;boost/functional/hash_fwd.hpp&gt;</code>
+          </para>
         </notes>
         <throws><para>
           Only throws if <code><functionname>hash_value</functionname>(std::iterator_traits&lt;It&gt;::value_type)</code>

hash/doc/tutorial.qbk

@@ -198,5 +198,15 @@ To calculate the hash of an iterator range you can use [funcref boost::hash_rang
     std::vector<std::string> some_strings;
     std::size_t hash = ``[funcref boost::hash_range]``(some_strings.begin(), some_strings.end());
 
-[endsect]
+Note that when writing template classes, you might not want to include the main
+hash header as it's quite an expensive include that brings in a lot of other
+headers, so instead you can include the `<boost/functional/hash_fwd.hpp>`
+header which forward declares [classref boost::hash],
+[funcref boost::hash_range] and [funcref boost::hash_combine]. You'll need to
+include the main header before instantiating [classref boost::hash]. When using
+a container that uses [classref boost::hash] it should do that for you, so your
+type will work fine with the boost hash containers. There's an example of this
+in [@boost:/libs/unordered/examples/template.hpp template.hpp] and
+[@boost:/libs/unordered/examples/template.cpp template.cpp].
 
+[endsect]