Add docs to conditionally skip plugs, closes #1165

lib/plug/builder.ex

@@ -50,6 +50,29 @@ defmodule Plug.Builder do
   By implementing the Plug API, `Plug.Builder` guarantees this module is a plug
   and can be handed to a web server or used as part of another pipeline.
 
+  ## Conditional plugs
+
+  Sometimes you may want to conditionally invoke a Plug in a pipeline. For example,
+  you may want to invoke `Plug.Parsers` only under certain routes. This can be done
+  by wrapping the module plug in a function plug. Instead of:
+
+      plug Plug.Parsers, parsers: [:urlencoded, :multipart], pass: ["text/*"]
+
+  You can write:
+
+      plug :conditional_parser
+
+      defp conditional_parser(%Plug.Conn{path_info: ["noparser" | _]} = conn, _opts) do
+        conn
+      end
+
+      @parser Plug.Parsers.init(parsers: [:urlencoded, :multipart], pass: ["text/*"])
+      defp conditional_parser(conn, _opts) do
+        Plug.Parsers.call(conn, @parser)
+      end
+
+  The above will invoke `Plug.Parsers` on all routes, except the ones under `/noparser`
+
   ## Overriding the default Plug API functions
 
   Both the `init/1` and `call/2` functions defined by `Plug.Builder` can be