Add a note about the BOOST_HASH_NO_EXTENSIONS macro, and fix some typos and

improve the markup in the hash documentation.


[SVN r33298]

hash/doc/changes.qbk

@@ -13,8 +13,8 @@
 * Use declarations for standard classes, so that the library
   doesn't need to include all of their headers
 * Deprecated the `<boost/functional/hash/*.hpp>` headers. Now a single header,
-  `<boost/functional/hash.hpp>` is used.
+  <[headerref boost/functional/hash.hpp]> is used.
-* Add support for the BOOST_HASH_NO_EXTENSIONS macro, which
+* Add support for the `BOOST_HASH_NO_EXTENSIONS` macro, which
   disables the extensions to TR1
 * Minor improvements to the hash functions for floating point numbers.
 

hash/doc/disable.qbk

@@ -0,0 +1,24 @@
+[section:disable Disabling The Extensions]
+
+While [classref boost::hash]'s extensions are generally useful, you might want
+to turn them of in order to check that your code will work with other
+implementations of TR1. To do this define the macro `BOOST_HASH_NO_EXTENSIONS`.
+When this macro is defined, only the specialisations detailed
+in TR1 will be declared. But, if you later undefine the macro and include
+<[headerref boost/functional/hash.hpp]> then the non-specialised form will be defined
+- activating the extensions.
+
+It is strongly recommended that you never undefine the macro - and only define
+it so that it applies to the complete translation unit, either by defining it
+at the beginning of the main source file or, preferably, by using a compiler
+switch or preference. And you really should never define it in header files.
+
+If you are writing a library which has code in the header which requires the
+extensions, then the best action is to tell users not to define the macro.
+Their code won't ['require] the macro.
+
+Translation units that are compiled with the macro defined will link with units
+that were compiled without it. This feature has been designed to avoid ODR
+violations.
+
+[endsect]

hash/doc/hash.qbk

@@ -17,6 +17,7 @@
 [include:hash intro.qbk]
 [include:hash tutorial.qbk]
 [include:hash portability.qbk]
+[include:hash disable.qbk]
 [include:hash changes.qbk]
 [xinclude ref.xml]
 [include:hash links.qbk]

hash/doc/portability.qbk

@@ -4,7 +4,7 @@
 
 __boost_hash__ is written to be as portable as possible, but unfortunately, several
 older compilers don't support argument dependent lookup (ADL) - the mechanism
-used for customisation.  On those compilers custom overloads for hash_value
+used for customisation.  On those compilers custom overloads for `hash_value`
 need to be declared in the boost namespace.
 
 On a strictly standards compliant compiler, an overload defined in the

hash/doc/tutorial.qbk

@@ -1,3 +1,6 @@
+[def __multi-index-short__ [@../../libs/multi_index/doc/index.html
+    Boost.MultiIndex]]
+
 [section:tutorial Tutorial]
 
 When using a hash index with __multi-index-short__, you don't need to do
@@ -19,7 +22,7 @@ associative containers and you wish to use
 
 To use [classref boost::hash] directly, create an instance and call it as a function:
 
-    #include <boost/functional/hash.hpp>
+    #include <``[headerref boost/functional/hash.hpp]``>
 
     int main()
     {
@@ -45,7 +48,8 @@ containing the hashes of the elements of a container:
 
 [section:custom Extending boost::hash for a custom data type]
 
-[classref boost::hash] is implemented by calling the function [funcref boost::hash_value hash_value].
+[classref boost::hash] is implemented by calling the function
+[funcref boost::hash_value hash_value].
 The namespace isn't specified so that it can detect overloads via argument
 dependant lookup. So if there is a free function `hash_value` in the same
 namespace as a custom type, it will get called.
@@ -108,7 +112,7 @@ and
 [blurb
 When writing a hash function, first look at how the equality function works.
 Objects that are equal must generate the same hash value.
-When objects are not equal the should generate different hash values.
+When objects are not equal they should generate different hash values.
 In this object equality was based just on the id, if it was based
 on the objects name and author the hash function should take them into account
 (how to do this is discussed in the next section).
@@ -146,8 +150,8 @@ the hash values for `x` and `y`. The function
         friend std::size_t hash_value(point const& p)
         {
             std::size_t seed = 0;
-            [funcref boost::hash_combine](seed, p.x);
+            ``[funcref boost::hash_combine]``(seed, p.x);
-            [funcref boost::hash_combine](seed, p.y);
+            ``[funcref boost::hash_combine]``(seed, p.y);
 
             return seed;
         }
@@ -163,9 +167,9 @@ Full code for this example is at
 [@../../libs/functional/hash/examples/point.cpp /libs/functional/hash/examples/point.cpp].
 
 [blurb
-'''
 When using [funcref boost::hash_combine] the order of the
 calls matters.
+'''
 <programlisting>
     std::size_t seed = 0;
     boost::hash_combine(seed, 1);
@@ -177,16 +181,16 @@ results in a different seed to:
     boost::hash_combine(seed, 2);
     boost::hash_combine(seed, 1);
 </programlisting>
+'''
 If you are calculating a hash value for data where the order of the data
 doesn't matter in comparisons (e.g. a set) you will have to ensure that the
 data is always supplied in the same order.
-'''
 ]
 
 To calculate the hash of an iterator range you can use [funcref boost::hash_range]:
 
     std::vector<std::string> some_strings;
-    std::size_t hash = [funcref boost::hash_range](some_strings.begin(), some_strings.end());
+    std::size_t hash = ``[funcref boost::hash_range]``(some_strings.begin(), some_strings.end());
 
 [endsect]