clean up error handler docs

docs/patterns/errorpages.rst

@@ -47,31 +47,34 @@ even if the application behaves correctly:
 Error Handlers
 --------------
 
-An error handler is a function, just like a view function, but it is
+An error handler is a function that returns a response when a type of error is
-called when an error happens and is passed that error.  The error is most
+raised, similar to how a view is a function that returns a response when a
-likely a :exc:`~werkzeug.exceptions.HTTPException`, but in one case it
+request URL is matched. It is passed the instance of the error being handled,
-can be a different error: a handler for internal server errors will be
+which is most likely a :exc:`~werkzeug.exceptions.HTTPException`. An error
-passed other exception instances as well if they are uncaught.
+handler for "500 Internal Server Error" will be passed uncaught exceptions in
+addition to explicit 500 errors.
 
 An error handler is registered with the :meth:`~flask.Flask.errorhandler`
-decorator and the error code of the exception (alternatively, you can use the
+decorator or the :meth:`~flask.Flask.register_error_handler` method. A handler
-:meth:`~flask.Flask.register_error_handler` function, e.g., when you're
+can be registered for a status code, like 404, or for an exception class.
-registering error handlers as part of your Application Factory).  Keep in mind
-that Flask will *not* set the error code for you, so make sure to also provide
-the HTTP status code when returning a response.delete_cookie.
 
-Please note that if you add an error handler for "500 Internal Server
+The status code of the response will not be set to the handler's code. Make
-Error", Flask will not trigger it if it's running in Debug mode.
+sure to provide the appropriate HTTP status code when returning a response from
+a handler.
 
-Here an example implementation for a "404 Page Not Found" exception::
+A handler for "500 Internal Server Error" will not be used when running in
+debug mode. Instead, the interactive debugger will be shown.
+
+Here is an example implementation for a "404 Page Not Found" exception::
 
     from flask import render_template
 
     @app.errorhandler(404)
     def page_not_found(e):
+        # note that we set the 404 status explicitly
         return render_template('404.html'), 404
 
-And, using an application factory pattern (see :ref:`app-factories`)::
+When using the :ref:`application factory pattern <app-factories>`::
 
     from flask import Flask, render_template
 
@@ -80,8 +83,8 @@ And, using an application factory pattern (see :ref:`app-factories`)::
 
     def create_app(config_filename):
         app = Flask(__name__)
-        # ...
         app.register_error_handler(404, page_not_found)
+        return app
 
 An example template might be this:
 
@@ -94,4 +97,3 @@ An example template might be this:
       <p>What you were looking for is just not there.
       <p><a href="{{ url_for('index') }}">go somewhere nice</a>
     {% endblock %}
-