From ac31c7e33cbea88d442133a71107a64d682a8fd9 Mon Sep 17 00:00:00 2001
From: Daniel James <daniel@calamity.org.uk>
Date: Sun, 21 Jun 2009 09:41:11 +0000
Subject: [PATCH] A few more comments in boost::hash.

[SVN r54139]
---
 include/boost/functional/hash/extensions.hpp | 17 +++++++++++---
 include/boost/functional/hash/hash.hpp       | 24 ++++++++++++++++++++
 2 files changed, 38 insertions(+), 3 deletions(-)

diff --git a/include/boost/functional/hash/extensions.hpp b/include/boost/functional/hash/extensions.hpp
index d173314..02f8bbb 100644
--- a/include/boost/functional/hash/extensions.hpp
+++ b/include/boost/functional/hash/extensions.hpp
@@ -17,6 +17,12 @@
 namespace boost
 {
 
+    //
+    // call_hash_impl
+    //
+
+    // On compilers without function template ordering, this deals with arrays.
+
 #if defined(BOOST_NO_FUNCTION_TEMPLATE_ORDERING)
     namespace hash_detail
     {
@@ -61,6 +67,11 @@ namespace boost
     }
 #endif // BOOST_NO_FUNCTION_TEMPLATE_ORDERING
 
+    //
+    // boost::hash
+    //
+
+
 #if !defined(BOOST_NO_TEMPLATE_PARTIAL_SPECIALIZATION)
 
     template <class T> struct hash
@@ -94,7 +105,7 @@ namespace boost
 
     // On compilers without partial specialization, boost::hash<T>
     // has already been declared to deal with pointers, so just
-    // need to supply the non-pointer version.
+    // need to supply the non-pointer version of hash_impl.
 
     namespace hash_detail
     {
@@ -126,8 +137,8 @@ namespace boost
 
 #else // Visual C++ 6.5
 
-    // There's probably a more elegant way to Visual C++ 6.5 to work
-    // but I don't know what it is.
+        // Visual C++ 6.5 has problems with nested member functions and
+        // applying const to const types in templates. So we get this:
 
         template <bool IsConst>
         struct hash_impl_msvc
diff --git a/include/boost/functional/hash/hash.hpp b/include/boost/functional/hash/hash.hpp
index 12283ff..6f8b313 100644
--- a/include/boost/functional/hash/hash.hpp
+++ b/include/boost/functional/hash/hash.hpp
@@ -378,6 +378,18 @@ namespace boost
     //
     // boost::hash
     //
+    
+    // Define the specializations required by the standard. The general purpose
+    // boost::hash is defined later in extensions.hpp if BOOST_HASH_NO_EXTENSIONS
+    // is not defined.
+    
+    // BOOST_HASH_SPECIALIZE - define a specialization for a type which is
+    // passed by copy.
+    //
+    // BOOST_HASH_SPECIALIZE_REF - define a specialization for a type which is
+    // passed by copy.
+    //
+    // These are undefined later.
 
 #if !BOOST_WORKAROUND(BOOST_MSVC, < 1300)
 #define BOOST_HASH_SPECIALIZE(type) \
@@ -465,7 +477,10 @@ namespace boost
 #undef BOOST_HASH_SPECIALIZE
 #undef BOOST_HASH_SPECIALIZE_REF
 
+// Specializing boost::hash for pointers.
+
 #if !defined(BOOST_NO_TEMPLATE_PARTIAL_SPECIALIZATION)
+
     template <class T>
     struct hash<T*>
         : public std::unary_function<T*, std::size_t>
@@ -482,7 +497,15 @@ namespace boost
 #endif
         }
     };
+
 #else
+
+    // For compilers without partial specialization, we define a
+    // boost::hash for all remaining types. But hash_impl is only defined
+    // for pointers in 'extensions.hpp' - so when BOOST_HASH_NO_EXTENSIONS
+    // is defined there will still be a compile error for types not supported
+    // in the standard.
+
     namespace hash_detail
     {
         template <bool IsPointer>
@@ -515,6 +538,7 @@ namespace boost
             ::BOOST_NESTED_TEMPLATE inner<T>
     {
     };
+
 #endif
 }