Error handling docs

docs/guide.1

@@ -266,6 +266,84 @@ var app = express\.createServer(
 .
 .IP "" 0
 .
+.P
+Alternatively we can \fIuse()\fR them which is useful when adding middleware within \fIconfigure()\fR blocks:
+.
+.IP "" 4
+.
+.nf
+
+app\.use(\'/\', connect\.logger({ format: \':method :uri\' }));
+.
+.fi
+.
+.IP "" 0
+.
+.SS "Error Handling"
+Express provides the \fIapp\.error()\fR method which receives exceptions thrown within a route, or passed to \fInext(err)\fR\. Below is an example which serves different pages based on our ad\-hoc \fINotFound\fR exception:
+.
+.IP "" 4
+.
+.nf
+
+function NotFound(msg){
+    this\.name = \'NotFound\';
+    Error\.call(this, msg);
+    Error\.captureStackTrace(this, arguments\.callee);
+}
+
+sys\.inherits(NotFound, Error);
+
+app\.get(\'/404\', function(req, res){
+    throw new NotFound;
+});
+
+app\.get(\'/500\', function(req, res){
+    throw new Error(\'keyboard cat!\');
+});
+.
+.fi
+.
+.IP "" 0
+.
+.P
+We can call \fIapp\.error()\fR several times as shown below\. Here we check for an instanceof \fINotFound\fR and show the 404 page, or we pass on to the next error handler\.
+.
+.IP "" 4
+.
+.nf
+
+app\.error(function(err, req, res, next){
+    if (err instanceof NotFound) {
+        res\.render(\'404\.jade\');
+    } else {
+        next(err);
+    }
+});
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Here we assume all errors as 500 for the simplicity of this demo, however you can choose whatever you like
+.
+.IP "" 4
+.
+.nf
+
+app\.error(function(err, req, res){
+    res\.render(\'500\.jade\', {
+       locals: {
+           error: err
+       }
+    });
+});
+.
+.fi
+.
+.IP "" 0
+.
 .SS "req\.header(key[, defaultValue])"
 Get the case\-insensitive request header \fIkey\fR, with optional \fIdefaultValue\fR:
 .
@@ -611,4 +689,19 @@ app\.get(\'/post/:id\', function(req, res){
 .fi
 .
 .IP "" 0
+.
+.SS "app\.error(function)"
+Adds an error handler \fIfunction\fR which will receive the exception as the first parameter:
+.
+.IP "" 4
+.
+.nf
+
+app\.error(function(err, req, res, next){
+    res\.send(err\.message, 500);
+});
+.
+.fi
+.
+.IP "" 0
 

docs/guide.html

@@ -173,6 +173,7 @@
 <li><a href="#Routing">Routing</a></li>
 <li><a href="#Passing-Route-Control">Passing Route Control</a></li>
 <li><a href="#Middleware">Middleware</a></li>
+<li><a href="#Error-Handling">Error Handling</a></li>
 <li><a href="#req-header-key-defaultValue-">req.header()</a></li>
 <li><a href="#req-accepts-type-">req.accepts()</a></li>
 <li><a href="#req-param-name-">req.param()</a></li>
@@ -190,6 +191,7 @@
 <li><a href="#app-disable-name-">app.disable()</a></li>
 <li><a href="#app-configure-env-function-function-">app.configure()</a></li>
 <li><a href="#app-redirect-name-val-">app.redirect()</a></li>
+<li><a href="#app-error-function-">app.error()</a></li>
 </ul>
 				<a href='http://github.com/visionmedia/express' id='logo'>Express</a> 
 				<p id="tagline">
@@ -381,6 +383,59 @@ <h3 id="Middleware">Middleware</h3>
 );
 </code></pre>
 
+<p>Alternatively we can <em>use()</em> them which is useful when adding middleware within <em>configure()</em> blocks:</p>
+
+<pre><code>app.use('/', connect.logger({ format: ':method :uri' }));
+</code></pre>
+
+<h3 id="Error-Handling">Error Handling</h3>
+
+<p>Express provides the <em>app.error()</em> method which receives exceptions thrown within a route,
+or passed to <em>next(err)</em>. Below is an example which serves different pages based on our
+ad-hoc <em>NotFound</em> exception:</p>
+
+<pre><code>function NotFound(msg){
+    this.name = 'NotFound';
+    Error.call(this, msg);
+    Error.captureStackTrace(this, arguments.callee);
+}
+
+sys.inherits(NotFound, Error);
+
+app.get('/404', function(req, res){
+    throw new NotFound;
+});
+
+app.get('/500', function(req, res){
+    throw new Error('keyboard cat!');
+});
+</code></pre>
+
+<p>We can call <em>app.error()</em> several times as shown below.
+Here we check for an instanceof <em>NotFound</em> and show the
+404 page, or we pass on to the next error handler.</p>
+
+<pre><code>app.error(function(err, req, res, next){
+    if (err instanceof NotFound) {
+        res.render('404.jade');
+    } else {
+        next(err);
+    }
+});
+</code></pre>
+
+<p>Here we assume all errors as 500 for the simplicity of
+this demo, however you can choose whatever you like</p>
+
+<pre><code>app.error(function(err, req, res){
+    res.render('500.jade', {
+       locals: {
+           error: err
+       } 
+    });
+});
+</code></pre>
+
 <h3 id="req-header-key-defaultValue-">req.header(key[, defaultValue])</h3>
 
 <p>Get the case-insensitive request header <em>key</em>, with optional <em>defaultValue</em>:</p>
@@ -613,6 +668,15 @@ <h3 id="app-redirect-name-val-">app.redirect(name, val)</h3>
 });
 </code></pre>
 
+<h3 id="app-error-function-">app.error(function)</h3>
+
+<p>Adds an error handler <em>function</em> which will receive the exception as the first parameter:</p>
+
+<pre><code>app.error(function(err, req, res, next){
+    res.send(err.message, 500);
+});
+</code></pre>
+
 </div>
 			</div>
 		</div>

docs/guide.md

@@ -161,6 +161,55 @@ passed to _express.createServer()_ as you would with a regular Connect server. F
 		connect.bodyDecoder()
 	);
 
+Alternatively we can _use()_ them which is useful when adding middleware within _configure()_ blocks:
+
+    app.use('/', connect.logger({ format: ':method :uri' }));
+
+### Error Handling
+
+Express provides the _app.error()_ method which receives exceptions thrown within a route,
+or passed to _next(err)_. Below is an example which serves different pages based on our
+ad-hoc _NotFound_ exception:
+
+	function NotFound(msg){
+	    this.name = 'NotFound';
+	    Error.call(this, msg);
+	    Error.captureStackTrace(this, arguments.callee);
+	}
+
+	sys.inherits(NotFound, Error);
+
+	app.get('/404', function(req, res){
+	    throw new NotFound;
+	});
+
+	app.get('/500', function(req, res){
+	    throw new Error('keyboard cat!');
+	});
+
+We can call _app.error()_ several times as shown below.
+Here we check for an instanceof _NotFound_ and show the
+404 page, or we pass on to the next error handler.
+
+	app.error(function(err, req, res, next){
+	    if (err instanceof NotFound) {
+	        res.render('404.jade');
+	    } else {
+	        next(err);
+	    }
+	});
+
+Here we assume all errors as 500 for the simplicity of
+this demo, however you can choose whatever you like
+
+	app.error(function(err, req, res){
+	    res.render('500.jade', {
+	       locals: {
+	           error: err
+	       } 
+	    });
+	});
+
 ### req.header(key[, defaultValue])
 
 Get the case-insensitive request header _key_, with optional _defaultValue_:
@@ -370,3 +419,11 @@ redirect _Location_ would be _/post/12/comments_.
     app.get('/post/:id', function(req, res){
         res.redirect('comments');
     });
+
+### app.error(function)
+
+Adds an error handler _function_ which will receive the exception as the first parameter:
+
+    app.error(function(err, req, res, next){
+		res.send(err.message, 500);
+	});