Add ref documentation and doxygen

doc/Jamfile.v2

@@ -5,14 +5,28 @@
 # Version 1.0. (See accompanying file LICENSE_1_0.txt
 # or copy at http://boost.org/LICENSE_1_0.txt)
 
+import doxygen ;
 import quickbook ;
 
+doxygen ref_reference
+  :
+    [ glob ../../../boost/core/ref.hpp ]
+  :
+    <doxygen:param>ENABLE_PREPROCESSING=YES
+    <doxygen:param>EXPAND_ONLY_PREDEF=YES
+    <doxygen:param>EXTRACT_ALL=NO
+    <doxygen:param>EXTRACT_PRIVATE=NO
+    <doxygen:param>HIDE_UNDOC_MEMBERS=YES
+    <doxygen:param>MACRO_EXPANSION=YES
+  ;
+
 xml core : core.qbk ;
 
 boostbook standalone
   :
     core
   :
+    <dependency>ref_reference
     <xsl:param>boost.root=http://boost.org/doc/libs/master
     <xsl:param>generate.section.toc.level=1
     <xsl:param>toc.max.depth=1

doc/core.qbk

@@ -1,3 +1,12 @@
+[/
+  Copyright (c) 2014 Glen Joseph Fernandes
+  glenfe at live dot com
+
+  Distributed under the Boost Software License,
+  Version 1.0. (See accompanying file LICENSE_1_0.txt
+  or copy at http://boost.org/LICENSE_1_0.txt)
+]
+
 [library Boost.Core
   [quickbook 1.5]
   [id core]
@@ -65,7 +74,7 @@ Currently, the Core library contains:
    [`boost::null_deleter`]
  ]
  [
-   [ref]
+   [[link core.ref ref]]
    [`boost::ref`]
  ]
  [
@@ -89,5 +98,6 @@ Currently, the Core library contains:
 [include:core no_exceptions_support.qbk]
 [include:core noncopyable.qbk]
 [include:core null_deleter.qbk]
+[include:core ref.qbk]
 [include:core scoped_enum.qbk]
 [include:core swap.qbk]

doc/ref.qbk

@@ -0,0 +1,58 @@
+[section:ref Header <boost/core/ref.hpp>]
+
+[section Introduction]
+
+The Ref library is a small library that is useful for passing
+references to function templates (algorithms) that would
+usually take copies of their arguments. It defines the class
+template `boost::reference_wrapper<T>`, two functions
+`boost::ref` and `boost::cref` that return instances of
+`boost::reference_wrapper<T>`, a function `boost::unwrap_ref`
+that unwraps a `boost::reference_wrapper<T>` or returns a
+reference to any other type of object, and the two traits
+classes `boost::is_reference_wrapper<T>` and
+`boost::unwrap_reference<T>`.
+
+The purpose of `boost::reference_wrapper<T>` is to contain a
+reference to an object of type `T`. It is primarily used to
+"feed" references to function templates (algorithms) that take
+their parameter by value.
+
+To support this usage, `boost::reference_wrapper<T>` provides
+an implicit conversion to `T&`. This usually allows the
+function templates to work on references unmodified.
+
+`boost::reference_wrapper<T>` is both CopyConstructible and
+Assignable (ordinary references are not Assignable).
+
+The `expression boost::ref(x)` returns a
+`boost::reference_wrapper<X>(x)` where `X` is the type of `x`.
+Similarly, `boost::cref(x)` returns a
+`boost::reference_wrapper<X const>(x)`.
+
+The expression `boost::unwrap_ref(x)` returns a
+`boost::unwrap_reference<X>::type&` where `X` is the type of
+`x`.
+
+The expression `boost::is_reference_wrapper<T>::value` is
+`true` if `T` is a `reference_wrapper`, and `false` otherwise.
+
+The type-expression `boost::unwrap_reference<T>::type` is
+`T::type` if `T` is a `reference_wrapper`, `T` otherwise.
+
+[endsect]
+
+[xinclude ref_reference.xml]
+
+[section Acknowledgments]
+
+`ref` and `cref` were originally part of the Tuple library by
+Jaakko J\u00E4rvi. They were "promoted to `boost::` status" by
+Peter Dimov because they are generally useful. Douglas Gregor
+and Dave Abrahams contributed `is_reference_wrapper` and
+`unwrap_reference`. Frank Mori Hess and Ronald Garcia
+contributed `boost::unwrap_ref`.
+
+[endsect]
+
+[endsect]