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]

include/boost/core/ref.hpp

@@ -18,6 +18,9 @@
 //  Copyright (C) 2001, 2002 Peter Dimov
 //  Copyright (C) 2002 David Abrahams
 //
+//  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://www.boost.org/LICENSE_1_0.txt)
@@ -25,22 +28,60 @@
 //  See http://www.boost.org/libs/bind/ref.html for documentation.
 //
 
+/**
+ @file
+*/
+
+/**
+ Boost namespace.
+*/
 namespace boost
 {
 
 // reference_wrapper
 
+/**
+ @brief Contains a reference to an object of type `T`.
+
+ `reference_wrapper` is primarily used to "feed" references to
+ function templates (algorithms) that take their parameter by
+ value. It provides an implicit conversion to `T&`, which
+ usually allows the function templates to work on references
+ unmodified.
+*/
 template<class T> class reference_wrapper
 {
 public:
+    /**
+     Type `T`.
+    */
     typedef T type;
 
+    /**
+     Constructs a `reference_wrapper` object that stores a
+     reference to `t`.
+
+     @remark Does not throw.
+    */
     BOOST_FORCEINLINE explicit reference_wrapper(T& t): t_(boost::addressof(t)) {}
 
+    /**
+     @return The stored reference.
+     @remark Does not throw.
+    */
     BOOST_FORCEINLINE operator T& () const { return *t_; }
 
+    /**
+     @return The stored reference.
+     @remark Does not throw.
+    */
     BOOST_FORCEINLINE T& get() const { return *t_; }
 
+    /**
+     @return A pointer to the object referenced by the stored
+       reference.
+     @remark Does not throw.
+    */
     BOOST_FORCEINLINE T* get_pointer() const { return t_; }
 
 private:
@@ -50,12 +91,22 @@ private:
 
 // ref
 
+/**
+ @cond
+*/
 # if defined( __BORLANDC__ ) && BOOST_WORKAROUND( __BORLANDC__, BOOST_TESTED_AT(0x581) )
 #  define BOOST_REF_CONST
 # else
 #  define BOOST_REF_CONST const
 # endif
+/**
+ @endcond
+*/
 
+/**
+ @return `reference_wrapper<T>(t)`
+ @remark Does not throw.
+*/
 template<class T> BOOST_FORCEINLINE reference_wrapper<T> BOOST_REF_CONST ref( T & t )
 {
     return reference_wrapper<T>(t);
@@ -63,6 +114,10 @@ template<class T> BOOST_FORCEINLINE reference_wrapper<T> BOOST_REF_CONST ref( T
 
 // cref
 
+/**
+ @return `reference_wrapper<T const>(t)`
+ @remark Does not throw.
+*/
 template<class T> BOOST_FORCEINLINE reference_wrapper<T const> BOOST_REF_CONST cref( T const & t )
 {
     return reference_wrapper<T const>(t);
@@ -72,11 +127,21 @@ template<class T> BOOST_FORCEINLINE reference_wrapper<T const> BOOST_REF_CONST c
 
 // is_reference_wrapper
 
+/**
+ @brief Determine if a type `T` is an instantiation of
+ `reference_wrapper`.
+
+ The value static constant will be true if the type `T` is a
+ specialization of `reference_wrapper`.
+*/
 template<typename T> struct is_reference_wrapper
 {
     BOOST_STATIC_CONSTANT( bool, value = false );
 };
 
+/**
+ @cond
+*/
 template<typename T> struct is_reference_wrapper< reference_wrapper<T> >
 {
     BOOST_STATIC_CONSTANT( bool, value = true );
@@ -101,13 +166,27 @@ template<typename T> struct is_reference_wrapper< reference_wrapper<T> const vol
 
 #endif // !defined(BOOST_NO_CV_SPECIALIZATIONS)
 
+/**
+ @endcond
+*/
+
+
 // unwrap_reference
 
+/**
+ @brief Find the type in a `reference_wrapper`.
+
+ The `typedef` type is `T::type` if `T` is a
+ `reference_wrapper`, `T` otherwise.
+*/
 template<typename T> struct unwrap_reference
 {
     typedef T type;
 };
 
+/**
+ @cond
+*/
 template<typename T> struct unwrap_reference< reference_wrapper<T> >
 {
     typedef T type;
@@ -132,8 +211,16 @@ template<typename T> struct unwrap_reference< reference_wrapper<T> const volatil
 
 #endif // !defined(BOOST_NO_CV_SPECIALIZATIONS)
 
+/**
+ @endcond
+*/
+
 // unwrap_ref
 
+/**
+ @return `unwrap_reference<T>::type&(t)`
+ @remark Does not throw.
+*/
 template<class T> BOOST_FORCEINLINE typename unwrap_reference<T>::type& unwrap_ref( T & t )
 {
     return t;
@@ -141,10 +228,16 @@ template<class T> BOOST_FORCEINLINE typename unwrap_reference<T>::type& unwrap_r
 
 // get_pointer
 
+/**
+ @cond
+*/
 template<class T> BOOST_FORCEINLINE T* get_pointer( reference_wrapper<T> const & r )
 {
     return r.get_pointer();
 }
+/**
+ @endcond
+*/
 
 } // namespace boost