Clarified docs a bit and improved the header docs for Exception Handling

files.

Author: NHDaly

GUIExceptionHandling.h

@@ -1,15 +1,20 @@
 //
-//  ErrorHandling.h
+//  ExceptionHandling.h
 //  GUI Widget Library
 //
+//  Definitions for the Exception Handling functions:
+//    ExceptionHandler* create_exception_handler(const Handler_t &handler);
+//    void call_exception_handlers(InputIterator begin, InputIterator end);
+//
 //  Created by Nathan Daly on 12/14/12.
 //  Copyright (c) 2012 Lions Entertainment. All rights reserved.
 //
 
-#ifndef GUI_ErrorHandling_h
-#define GUI_ErrorHandling_h
 
-#include "GUIExceptionHandling_Impl.h" // For ErrorCatcher and ErrorCatcher_Impl
+#ifndef GUI_Exception_Handling_h
+#define GUI_Exception_Handling_h
+
+#include "GUIExceptionHandling_Impl.h" // Contains details irrelevant to clients
 
 namespace GUIExceptionHandling {
 
@@ -21,9 +26,9 @@ ExceptionHandler* create_exception_handler(const Handler_t &handler) {
     return new ExceptionHandler_Impl<Exception_t, Handler_t>(handler);
 }
 
-// REQUIRES: This function MUST be called from within a catch(){} block!
 // Loop through error handlers and handle any errors. If no handler matches
 //  the error, it will be rethrown out of the function.
+// REQUIRES: This function MUST be called from within a catch(){} block!
 template <typename InputIterator>
 void call_exception_handlers(InputIterator begin, InputIterator end) {
     call_exception_handlers_helper(begin, end, false);
@@ -35,11 +40,12 @@ void call_exception_handlers_helper(InputIterator begin,
 
     try {
         // Create a vector of handlers
-        // (Since try_catch is virtual, it cannot be templated,
-        //                                              so it requires a vector.)
+        // (Since try_rethrow_catch is virtual, it cannot be templated,
+        //                                             so it requires a vector.)
         std::vector<ExceptionHandler*> catchers(begin, end);
 
-        catchers.front()->try_catch(++catchers.begin(), catchers.end(), handled);
+        catchers.front()->try_rethrow_catch(++catchers.begin(),
+                                            catchers.end(), handled);
 
     }
     catch (...) {
@@ -51,4 +57,4 @@ void call_exception_handlers_helper(InputIterator begin,
 
 } // namespace GUIExceptionHandling
 
-#endif /* GUI_ErrorHandling_h */
+#endif /* GUI_Exception_Handling_h */

GUIExceptionHandling_Impl.h

@@ -1,13 +1,15 @@
 //
-//  Error_Handling_Impl.h
+//  ExceptionHandling_Impl.h
 //  GUI Widget Library
 //
+//  Implementation for the ExceptionHandler class.
+//
 //  Created by Nathan Daly on 2/18/13.
-//  Copyright (c) 2013 Lions Entertainment. All rights reserved.
+//  Referenced from .
 //
 
-#ifndef GUI_Error_Handling_Impl_h
-#define GUI_Error_Handling_Impl_h
+#ifndef GUI_Exception_Handling_Impl_h
+#define GUI_Exception_Handling_Impl_h
 
 #include <vector>
 
@@ -17,36 +19,36 @@ namespace GUIExceptionHandling {
 template <typename Exception_t, typename Handler_t>
 class ExceptionHandler_Impl;
 
-    
+
 // Abstract ExceptionHandler Base Class.
 // Derived class will be templated for Error type and Handler type.
 class ExceptionHandler {
 private:    // Everything is private so that this can only be used as a base
             //  class for the ExceptionHandler_Impl class.
-
+    
 
     // A virtual function cannot be templated, so we require that try_catch,
     //  below, use a vector::iterator.
     typedef std::vector<ExceptionHandler*>::iterator ExceptionHandlerIter_t;
 
     // Recursive function call to iterate through list and try-catch on
     // currently thrown exception.
-    virtual void try_catch(ExceptionHandlerIter_t begin,
-                           ExceptionHandlerIter_t end, bool &handled) = 0;
+    virtual void try_rethrow_catch(ExceptionHandlerIter_t begin,
+                                   ExceptionHandlerIter_t end, bool &handled)=0;
 
 
     // This is the public interface for interacting with ExceptionHandlers
     template <typename InputIterator>
     friend void call_exception_handlers_helper(InputIterator begin,
                                                InputIterator end, bool handled);
-
+    
     // The only actual derived class that will use this class's functions.
     template <typename Exception_t, typename Handler_t>
     friend class ExceptionHandler_Impl;
 };
 
 
-// Implementation of ExceptionHandler. Nests try statements for all 
+// Implementation of ExceptionHandler. Nests try statements for all
 // ExceptionHandlers passed in, and rethrows the current exception.
 // Then each ExceptionHandler attempts to catch during the unravelling.
 //
@@ -55,8 +57,8 @@ class ExceptionHandler {
 template <typename Exception_t, typename Handler_t>
 class ExceptionHandler_Impl : public ExceptionHandler {
 private:    // Everything is private, so that ExceptionHandler_Impl isn't
-            //  created anywhere but from create_exception_handler().
-
+    //  created anywhere but from create_exception_handler().
+    
 
     // handler_ should be a callable entity s.t. handler_(Exception_t) is valid.
     // NOTE: handler_ will be copied.
@@ -66,16 +68,16 @@ class ExceptionHandler_Impl : public ExceptionHandler {
     // RESULT: handled will be set to true if any ExceptionHandler successfully
     // handled the current exception.
     // REQUIRES: this must be called from inside a catch{} block.
-    virtual void try_catch(ExceptionHandlerIter_t begin,
-                           ExceptionHandlerIter_t end, bool &handled) {
+    virtual void try_rethrow_catch(ExceptionHandlerIter_t begin,
+                                   ExceptionHandlerIter_t end, bool &handled) {
 
         // nest a try block for each ExceptionHandler
         try {
             if (begin == end) { // base case
                 throw;
             }
             ExceptionHandler *next = *begin;
-            next->try_catch(++begin, end, handled); // unravel until end
+            next->try_rethrow_catch(++begin, end, handled); // unravel until end
         }
         // Each ExceptionHandler gets a chance to try to catch the exception.
         catch(const Exception_t &e) { // Will only catch if e is of Exception_t
@@ -93,7 +95,7 @@ class ExceptionHandler_Impl : public ExceptionHandler {
 private:
     Handler_t handler;
 };
-    
+
 } // namespace GUIExceptionHandling
 
-#endif /* GUI_Error_Handling_Impl_h */
+#endif /* GUI_Exception_Handling_Impl_h */