Plug documentation edits

lib/plug.ex

@@ -8,8 +8,9 @@ defmodule Plug do
 
   ### Function plugs
 
-  A function plug is any function that receives a connection and a set of
-  options and returns a connection. Its type signature must be:
+  A function plug is by definition any function that receives a connection
+  and a set of options and returns a connection. Function plugs must have
+  the following type signature:
 
       (Plug.Conn.t, Plug.opts) :: Plug.Conn.t
 
@@ -52,8 +53,7 @@ defmodule Plug do
 
   ## The Plug pipeline
 
-  The `Plug.Builder` module provides conveniences for building plug
-  pipelines.
+  The `Plug.Builder` module provides conveniences for building plug pipelines.
   """
 
   @type opts ::
@@ -72,26 +72,29 @@ defmodule Plug do
   require Logger
 
   @doc """
-  Run a series of Plugs at runtime.
+  Run a series of plugs at runtime.
 
   The plugs given here can be either a tuple, representing a module plug
   and their options, or a simple function that receives a connection and
   returns a connection.
 
-  If any of the plugs halt, the remaining plugs are not invoked. If the
-  given connection was already halted, none of the plugs are invoked
-  either.
+  If any plug halts, the connection won't invoke the remaining plugs. If the
+  given connection was already halted, none of the plugs are invoked either.
 
-  While `Plug.Builder` works at compile-time, this is a straight-forward
-  alternative that works at runtime.
+<<<<<<< HEAD
+  While `Plug.Builder` is designed to operate at compile-time, the `run` function
+=======
+  While Plug.Builder is designed to operate at compile-time, the `run` function
+>>>>>>> origin/plug_doc_edits
+  serves as a straightforward alternative for runtime executions.
 
   ## Examples
 
       Plug.run(conn, [{Plug.Head, []}, &IO.inspect/1])
 
   ## Options
 
-    * `:log_on_halt` - a log level to be used if a Plug halts
+    * `:log_on_halt` - a log level to be used if a plug halts
 
   """
   @spec run(Plug.Conn.t(), [{module, opts} | (Plug.Conn.t() -> Plug.Conn.t())], Keyword.t()) ::
@@ -135,11 +138,11 @@ defmodule Plug do
   defp do_run(conn, [], _level), do: conn
 
   @doc """
-  Forwards requests to another Plug setting the connection to a trailing subpath of the request.
+  Forwards requests to another plug while setting the connection to a trailing subpath of the request.
 
-  The `path_info` on the forwarded connection will only include the trailing segments
-  of the request path supplied to forward, while `conn.script_name` will
-  retain the correct base path for e.g. url generation.
+  The `path_info` on the forwarded connection will only include the request path trailing segments
+  supplied to the `forward` function. The `conn.script_name` attribute retains the correct base path,
+  e.g., url generation.
 
   ## Example
 

lib/plug/builder.ex

@@ -21,21 +21,20 @@ defmodule Plug.Builder do
         end
       end
 
-  Multiple plugs can be defined with the `plug/2` macro, forming a pipeline.
-  The plugs in the pipeline will be executed in the order they've been added
-  through the `plug/2` macro. In the example above, `Plug.Logger` will be
-  called first and then the `:hello` function plug will be called on the
-  resulting connection.
+  The `plug/2` macro forms a pipeline by defining multiple plugs. Each plug
+  in the pipeline is executed from top to bottom. In the example above, the
+  `Plug.Logger` module plug is called before the `:hello` function plug, so
+  the function plug will be called on the module plug's resulting connection.
 
-  `Plug.Builder` also imports the `Plug.Conn` module, making functions like
-  `send_resp/3` available.
+  `Plug.Builder` imports the `Plug.Conn` module so functions like `send_resp/3`
+  are available.
 
   ## Options
 
   When used, the following options are accepted by `Plug.Builder`:
 
     * `:init_mode` - the environment to initialize the plug's options, one of
-      `:compile` or `:runtime`. Defaults `:compile`.
+      `:compile` or `:runtime`. The default value is `:compile`.
 
     * `:log_on_halt` - accepts the level to log whenever the request is halted
 
@@ -45,8 +44,8 @@ defmodule Plug.Builder do
 
   ## Plug behaviour
 
-  Internally, `Plug.Builder` implements the `Plug` behaviour, which means both
-  the `init/1` and `call/2` functions are defined.
+  `Plug.Builder` defines the `init/1` and `call/2` functions by implementing
+  the `Plug` behaviour.
 
   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.
@@ -86,9 +85,9 @@ defmodule Plug.Builder do
 
   ## Halting a plug pipeline
 
-  A plug pipeline can be halted with `Plug.Conn.halt/1`. The builder will
-  prevent further plugs downstream from being invoked and return the current
-  connection. In the following example, the `Plug.Logger` plug never gets
+  `Plug.Conn.halt/1` halts a plug pipeline. `Plug.Builder` prevents plugs
+  downstream from being invoked and returns the current connection.
+  In the following example, the `Plug.Logger` plug never gets
   called:
 
       defmodule PlugUsingHalt do