From 9b4f7a1a1599418bfd264fc4fed8be37a826649f Mon Sep 17 00:00:00 2001
From: mark_story <mark@mark-story.com>
Date: Thu, 25 Nov 2010 07:23:37 -0500
Subject: [PATCH] More documentation.

---
 cake/libs/error_handler.php      | 22 ++++++++++++++++++++--
 cake/libs/exception_renderer.php | 13 ++++++-------
 2 files changed, 26 insertions(+), 9 deletions(-)

diff --git a/cake/libs/error_handler.php b/cake/libs/error_handler.php
index 787c905f9..48f06c1fd 100644
--- a/cake/libs/error_handler.php
+++ b/cake/libs/error_handler.php
@@ -21,8 +21,12 @@
  */
 
 /**
- * Error Handler provides basic error and exception handling for your application. It Captures and 
- * handles all unhandled exceptions. Displays helpful framework errors when debug > 1.
+ *
+ * Error Handler provides basic error and exception handling for your application. It captures and 
+ * handles all unhandled exceptions and errors. Displays helpful framework errors when debug > 1.
+ *
+ * ### Uncaught exceptions
+ *
  * When debug < 1 a CakeException will render 404 or  500 errors.  If an uncaught exception is thrown
  * and it is a type that ErrorHandler does not know about it will be treated as a 500 error.
  *
@@ -68,6 +72,20 @@
  * errors will be logged to CakeLog.  You can control which errors are logged by setting
  * `Error.level` in your core.php.
  *
+ * #### Logging errors
+ *
+ * When ErrorHandler is used for handling errors, you can enable error logging by setting `Error.log` to true.
+ * This will log all errors to the configured log handlers.
+ *
+ * #### Controlling what errors are logged/displayed
+ *
+ * You can control which errors are logged / displayed by ErrorHandler by setting `Error.level`.  Setting this
+ * to one or a combination of a few of the E_* constants will only enable the specified errors.
+ *
+ * e.g. `Configure::write('Error.level', E_ALL & ~E_NOTICE);`
+ *
+ * Would enable handling for all non Notice errors.
+ *
  * @package       cake
  * @subpackage    cake.cake.libs
  * @see ExceptionRenderer for more information on how to customize exception rendering.
diff --git a/cake/libs/exception_renderer.php b/cake/libs/exception_renderer.php
index cb795d212..a83e25cb4 100644
--- a/cake/libs/exception_renderer.php
+++ b/cake/libs/exception_renderer.php
@@ -27,24 +27,23 @@
  * When debug < 1 a CakeException will render 404 or  500 errors.  If an uncaught exception is thrown
  * and it is a type that ExceptionHandler does not know about it will be treated as a 500 error.
  *
- * ### Implementing application specific exception handling
+ * ### Implementing application specific exception rendering
  *
  * You can implement application specific exception handling in one of a few ways:
  *
  * - Create a AppController::appError();
- * - Create an AppError class.
+ * - Create a subclass of ExceptionRenderer and configure it to be the `Exception.renderer`
  *
  * #### Using AppController::appError();
  *
  * This controller method is called instead of the default exception handling.  It receives the 
  * thrown exception as its only argument.  You should implement your error handling in that method.
  *
- * #### Using an AppError class
+ * #### Using a subclass of ExceptionRenderer
  *
- * This approach gives more flexibility and power in how you handle exceptions.  You can create 
- * `app/libs/app_error.php` and create a class called `AppError`.  The core ErrorHandler class
- * will attempt to construct this class and let it handle the exception. This provides a more
- * flexible way to handle exceptions in your application.
+ * Using a subclass of ExceptionRenderer gives you full control over how Exceptions are rendered, you 
+ * can configure your class in your core.php, with `Configure::write('Exception.renderer', 'MyClass');`
+ * You should place any custom exception renderers in `app/libs`.
  *
  * @package       cake
  * @subpackage    cake.cake.libs