Add ref documentation and doxygen

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