Added documentation comments. Added a policy.

git-svn-id: svn://svn.code.sf.net/p/loki-lib/code/trunk@955 7ec92016-0320-0410-acc4-a06ded1c099a

include/loki/CheckReturn.h

@@ -45,18 +45,20 @@ namespace Loki
 ///  primitive (bool, int, etc...) a pointer, or an enum (such as an error
 ///  condition enum).  It can work with other types that have cheap copy
 ///  operations.
-///
-///  \par OnError Policy
 ///  - OnError is a policy class indicating how to handle the situation when a
 ///  caller does not check or copy the returned value.  Loki provides some
 ///  policy classs and you may also write your own.  For example, you can write
-///  a policy to throw an exception or create a message box when the function
-///  ignores the return value.  If your write your own, you only need to provide
-///  a function named "run".
+///  a policy to create a message box when the function ignores the return value.
+///  That would quickly tell you places where code ignores the function call.
+///  If your write your own, you only need a templated class or struct with a
+///  public function named "run" that accepts a reference to a const value.
 ///
+/// @par Provided Policy Classes
 ///  - IgnoreReturnValue Deliberately ignores when the caller ignores the return value.
 ///  - TriggerAssert Asserts in debug builds if the caller ignores the return value.
 ///  - FprintfStderr Prints out an error message if the caller ignores the return value.
+///  - ThrowTheValue Throws the ignored value as an exception.
+///  - ThrowLogicError Throws a logic_error exception to indicate a programming error.
 ////////////////////////////////////////////////////////////////////////////////
 
 
@@ -65,7 +67,25 @@ struct IgnoreReturnValue
 {
 	static void run(const T&)
 	{
-	    /// Do nothing at all.
+		/// Do nothing at all.
+	}
+};
+
+template<class T>
+struct ThrowTheValue
+{
+	static void run(const T & value )
+	{
+		throw value;
+	}
+};
+
+template<class T>
+struct ThrowLogicError
+{
+	static void run( const T & )
+	{
+		throw ::std::logic_error( "CheckReturn: return value was not checked.\n" );
 	}
 };
 
@@ -74,7 +94,7 @@ struct TriggerAssert
 {
 	static void run(const T&)
 	{
-        assert( 0 );
+		assert( 0 );
 	}
 };
 
@@ -83,7 +103,7 @@ struct FprintfStderr
 {
 	static void run(const T&)
 	{
-		fprintf(stderr, "CheckReturn: return value was not checked\n");
+		fprintf(stderr, "CheckReturn: return value was not checked.\n");
 	}
 };
 
@@ -94,45 +114,45 @@ class CheckReturn
 {
 public:
 
-    /// Conversion constructor changes Value type to CheckReturn type.
-    inline CheckReturn( const Value & value ) :
-        m_value( value ), m_checked( false ) {}
+	/// Conversion constructor changes Value type to CheckReturn type.
+	inline CheckReturn( const Value & value ) :
+		m_value( value ), m_checked( false ) {}
 
-    /// Copy-constructor allows functions to call another function within the
-    /// return statement.  The other CheckReturn's m_checked flag is set since
-    /// its duty has been passed to the m_checked flag in this one.
-    inline CheckReturn( const CheckReturn & that ) :
-        m_value( that.m_value ), m_checked( false )
-    { that.m_checked = true; }
+	/// Copy-constructor allows functions to call another function within the
+	/// return statement.  The other CheckReturn's m_checked flag is set since
+	/// its duty has been passed to the m_checked flag in this one.
+	inline CheckReturn( const CheckReturn & that ) :
+		m_value( that.m_value ), m_checked( false )
+	{ that.m_checked = true; }
 
-    /// Destructor checks if return value was used.
-    inline ~CheckReturn( void )
-    {
+	/// Destructor checks if return value was used.
+	inline ~CheckReturn( void )
+	{
 		// If m_checked is false, then a function failed to check the
-        // return value from a function call.
+		// return value from a function call.
 		if (!m_checked)
 			OnError<Value>::run(m_value);
-    }
+	}
 
-    /// Conversion operator changes CheckReturn back to Value type.
-    inline operator Value ( void )
-    {
-        m_checked = true;
-        return m_value;
-    }
+	/// Conversion operator changes CheckReturn back to Value type.
+	inline operator Value ( void )
+	{
+		m_checked = true;
+		return m_value;
+	}
 
 private:
-    /// Default constructor not implemented.
-    CheckReturn( void );
+	/// Default constructor not implemented.
+	CheckReturn( void );
 
-    /// Copy-assignment operator not implemented.
-    CheckReturn & operator = ( const CheckReturn & that );
+	/// Copy-assignment operator not implemented.
+	CheckReturn & operator = ( const CheckReturn & that );
 
-    /// Copy of returned value.
-    Value m_value;
+	/// Copy of returned value.
+	Value m_value;
 
-    /// Flag for whether calling function checked return value yet.
-    mutable bool m_checked;
+	/// Flag for whether calling function checked return value yet.
+	mutable bool m_checked;
 };
 
 // ----------------------------------------------------------------------------