Rewrite the boost::throws() reference documentation. Add tests of boost::throws() using the divide() function from the reference documentation. Having tests will allow us to change the implementation of throws() without fear of silently breaking it.

test/error_code_test.cpp

@@ -56,6 +56,50 @@ namespace
     ss >> s;
     BOOST_TEST( s == expected );
   }
+
+  //  throws_function_test  ------------------------------------------------------------//
+
+  //  usage example
+
+  int divide(int dividend, int divisor, boost::system::error_code& ec = boost::throws())
+  {
+    if (divisor == 0)                            // is there an error?
+    {
+      if (&ec == &boost::throws())               // throw on error
+        throw "oops!";                           // whatever exception you prefer
+      ec = error_code(EDOM, generic_category()); // report error via error_code
+      return 0;
+    }
+    
+    if (&ec != &boost::throws())                 // error reporting via error_code
+      ec.clear();
+    return dividend / divisor;
+  }
+
+  //  test usage example
+
+  void test_throws_usage()
+  {
+    std::cout << "Test throws() example and usage...\n";
+    error_code ec;
+
+    // no error tests
+    BOOST_TEST_EQ((divide(10, 2)), 5);        // no error, report via exception
+    ec = make_error_code(errc::argument_out_of_domain);
+    BOOST_TEST_EQ((divide(10, 5, ec)), 2);    // no error, report via error_code
+    BOOST_TEST(!ec);
+
+    ec = make_error_code(errc::argument_out_of_domain);
+    BOOST_TEST_EQ((divide(10, 0, ec)), 0);    // error, report via error_code
+    BOOST_TEST(ec);
+
+    bool exception_thrown = false;            
+    try
+      { divide(10, 0); }                      // error, report via exception
+    catch (...)
+      { exception_thrown = true; }            
+    BOOST_TEST(exception_thrown);
+  }
 }
 
 //  main  ------------------------------------------------------------------------------//
@@ -202,6 +246,8 @@ int main( int, char ** )
   BOOST_TEST( econd.message() != "" );
   BOOST_TEST( econd.message().substr( 0, 13) != "Unknown error" );
 
+  test_throws_usage();
+
 #ifdef BOOST_WINDOWS_API
   std::cout << "Windows tests...\n";
   // these tests probe the Windows errc decoder