Rework middleware docs to discuss query middleware

docs/middleware.jade

@@ -3,12 +3,32 @@ extends layout
 block content
   h2 Middleware
   :markdown
-    Middleware are functions which are passed control of flow during execution of document [init](./api.html#document_Document-init), [validate](./api.html#document_Document-validate), [save](./api.html#model_Model-save) and [remove](./api.html#model_Model-remove) methods. Middleware are executed at the document level, not the Model level.
-    There are two types of middleware, `pre` and [post](#post). Let's start with `pre`.
+    Middleware (also called pre and post *hooks*) are functions which are passed
+    control during execution of asynchronous functions. Middleware is specified
+    on the schema level and is useful for writing [plugins](./plugins.html).
+    Mongoose 4.0 has 2 types
+    of middleware: document middleware and query middleware.
+    Document middleware is supported for the following document functions.
+
+    * [init](./api.html#document_Document-init)
+    * [validate](./api.html#document_Document-validate)
+    * [save](./api.html#model_Model-save)
+    * [remove](./api.html#model_Model-remove)
+
+    Query middleware is supported for the following Model and Query functions.
+
+    * [count](./api.html#query_Query-count)
+    * [find](./api.html#query_Query-find)
+    * [findOne](./api.html#query_Query-findOne)
+    * [findOneAndUpdate](./api.html#query_Query-findOneAndUpdate)
+    * [update](./api.html#query_Query-update)
+
+    Both document middleware and query middleware support pre and post hooks.
+    How pre and post hooks work is described in more detail below.
 
   h3 Pre
   :markdown
-    There are two types of `pre` middleware, serial and parallel.
+    There are two types of `pre` hooks, serial and parallel.
   h4 Serial
   :markdown
     Serial middleware are executed one after another, when each middleware calls `next`.
@@ -46,7 +66,8 @@ block content
           li notifications
   h4 Error handling
   :markdown
-    If any middleware calls `next` or `done` with an `Error` instance, the flow is interrupted, and the error is passed to the callback.
+    If any middleware calls `next` or `done` with an error, the flow
+    is interrupted, and the error is passed to the callback.
   :js
     schema.pre('save', function (next) {
       var err = new Error('something went wrong');
@@ -61,7 +82,11 @@ block content
 
   h3#post Post middleware
   :markdown
-    [post](/docs/api.html#schema_Schema-post) middleware are executed _after_ the hooked method and all of its `pre` middleware have completed. `post` middleware do not directly receive flow control, e.g. no `next` or `done` callbacks are passed to it. `post` hooks are a way to register traditional event listeners for these methods.
+    [post](/docs/api.html#schema_Schema-post) middleware are executed _after_
+    the hooked method and all of its `pre` middleware have completed.
+    `post` middleware do not directly receive flow control, e.g. no `next` or
+    `done` callbacks are passed to it. `post` hooks are a way to register
+    traditional event listeners for these methods.
 
   :js
     schema.post('init', function (doc) {
@@ -77,12 +102,23 @@ block content
       console.log('%s has been removed', doc._id);
     })
 
-  h3#notes Notes on findAndUpdate()
+  h3#notes Notes on findAndUpdate() and Query Middleware
   :markdown
-    `pre` and `post` are not called for update operations executed directly on the database, including `Model.update`,`.findByIdAndUpdate`,`.findOneAndUpdate`, `.findOneAndRemove`,and `.findByIdAndRemove`.
+    Pre and post `save()` hooks are **not** executed on `update()`,
+    `findOneAndUpdate()`, etc. You can see a more detailed discussion why in
+    [this GitHub issue](http://github.com/LearnBoost/mongoose/issues/964).
+    Mongoose 4.0 has distinct hooks for these functions.
 
-    In order to utilize `pre` or `post` middleware, you should `find()` the document, and call the `init`, `validate`, `save`, or `remove` functions on the document.  See [explanation](http://github.com/LearnBoost/mongoose/issues/964).
+  :js
+    schema.pre('update', function() {
+      this.start = Date.now();
+    });
+
+    schema.post('update', function() {
+      console.log('update() took ' + (Date.now() - this.start) + ' millis');
+    });
 
   h3#next Next Up
   :markdown
-    Now that we've covered `middleware`, let's take a look at Mongoose's approach to faking JOINs with its query [population](/docs/populate.html) helper.
+    Now that we've covered middleware, let's take a look at Mongoose's approach
+    to faking JOINs with its query [population](/docs/populate.html) helper.