implement feedback

lib/server.js

@@ -497,9 +497,6 @@ Server.prototype.pre = function pre() {
  * the overhead of the restify framework. You can not yield the event loop in
  * this handler.
  *
- * This is useful in cases where you want to make quick decisions about a
- * request, for example when shedding load.
- *
  * The function handler accepts two parameters: req, res. If you want restify
  * to ignore this request, return false from your handler. Return true or
  * undefined to let restify continue handling the request.
@@ -512,8 +509,22 @@ Server.prototype.pre = function pre() {
  *
  * The only work restify does for a first handler is to increment the number of
  * inflightRequests prior to calling the chain, and decrement that value if the
- * handler returns false.
+ * handler returns false. Returning anything other than true, false, undefined,
+ * or null will cause an exception to be thrown.
  *
+ * Since server.first is designed to bypass the restify framework, there are
+ * naturally trade-offs you make when using this API:
+ *  * Standard restify lifecycle events such as 'after' are not triggered for
+ *    any request that you return false from a handler for
+ *  * Invoking any of the restify req/res APIs from within a first handler is
+ *    unspecified behavior, as the restify framework hasn't built up state for
+ *    the request yet.
+ *  * There are no request timers available at the time that the first chain
+ *    runs.
+ *  * And more! Beware doing anything with restify in these handlers. They are
+ *    designed to give you similar access to the req/res as you would have if
+ *    you were directly using node.js' http module, they are outside of the
+ *    restify framework!
  * @public
  * @memberof Server
  * @instance
@@ -527,8 +538,8 @@ Server.prototype.pre = function pre() {
  * Takes one or more functions.
  * @returns {Object} returns self
  * @example
- * sever.first(function(req, res) {
- *   if(server._inflightRequests > 100) {
+ * server.first(function(req, res) {
+ *   if(server.inflightRequests() > 100) {
  *     res.statusCode = 503;
  *     res.end();
  *     return false