docs(middleware): suggest using return next() to stop middleware ex…

…ecution

Fix #5866

docs/middleware.jade

@@ -50,13 +50,29 @@ block content
     There are two types of `pre` hooks, serial and parallel.
   h4#serial Serial
   :markdown
-    Serial middleware are executed one after another, when each middleware calls `next`.
+    Serial middleware functions are executed one after another, when each
+    middleware calls `next`.
   :js
     var schema = new Schema(..);
     schema.pre('save', function(next) {
       // do stuff
       next();
     });
+  :markdown
+    The `next()` call does **not** stop the rest of the code in your middleware function from executing. Use
+    [the early `return` pattern](https://www.bennadel.com/blog/2323-use-a-return-statement-when-invoking-callbacks-especially-in-a-guard-statement.htm)
+    if you want to stop execution when you call `next()`.
+  :js
+    var schema = new Schema(..);
+    schema.pre('save', function(next) {
+      if (foo()) {
+        console.log('calling next!');
+        // `return next();` will make sure the rest of this function doesn't run
+        /*return*/ next();
+      }
+      // Unless you comment out the `return` above, 'after next' will print
+      console.log('after next');
+    });
   h4#parallel Parallel
   p
     | Parallel middleware offer more fine-grained flow control.