From d2fe7bddd0e982bb07ea6b9a2e262bcbb36e3f59 Mon Sep 17 00:00:00 2001 From: Brad Hanks Date: Fri, 8 Sep 2023 11:27:02 -0600 Subject: [PATCH 1/4] removed passive voice, added clarity --- lib/plug/builder.ex | 25 ++++++++++++------------- 1 file changed, 12 insertions(+), 13 deletions(-) diff --git a/lib/plug/builder.ex b/lib/plug/builder.ex index 12109341..580b2bb1 100644 --- a/lib/plug/builder.ex +++ b/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 From cff74625ca6353710e80debb7cb30f7147cb8f09 Mon Sep 17 00:00:00 2001 From: Hissssst <37012324+hissssst@users.noreply.github.com> Date: Sun, 25 Jun 2023 01:50:54 +0400 Subject: [PATCH 2/4] Remove list guard in Plug.Conn.merge_assigns and merge_private (#1152) --- lib/plug.ex | 29 ++++++++++++++--------------- 1 file changed, 14 insertions(+), 15 deletions(-) diff --git a/lib/plug.ex b/lib/plug.ex index 9b3e762f..485283af 100644 --- a/lib/plug.ex +++ b/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,18 +72,17 @@ 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. + While Plug.Builder is designed to operate at compile-time, the `run` function + serves as a straightforward alternative for runtime executions. ## Examples @@ -91,7 +90,7 @@ defmodule Plug do ## 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 +134,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 From 2ad58b38ceb8da109f251011c764b2e02889e6b3 Mon Sep 17 00:00:00 2001 From: Hissssst <37012324+hissssst@users.noreply.github.com> Date: Sun, 25 Jun 2023 01:50:54 +0400 Subject: [PATCH 3/4] Remove list guard in Plug.Conn.merge_assigns and merge_private (#1152) --- lib/plug.ex | 29 ++++++++++++++--------------- 1 file changed, 14 insertions(+), 15 deletions(-) diff --git a/lib/plug.ex b/lib/plug.ex index 9b3e762f..4fd2da7a 100644 --- a/lib/plug.ex +++ b/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,18 +72,17 @@ 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. + While `Plug.Builder` is designed to operate at compile-time, the `run` function + serves as a straightforward alternative for runtime executions. ## Examples @@ -91,7 +90,7 @@ defmodule Plug do ## 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 +134,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 From 2ae586438a4fa848812c5c30f4b6b718fbc277f2 Mon Sep 17 00:00:00 2001 From: Brad Hanks Date: Fri, 22 Dec 2023 20:19:16 -0700 Subject: [PATCH 4/4] consistent 'Plug.Builder' formatting --- lib/plug.ex | 4 ---- 1 file changed, 4 deletions(-) diff --git a/lib/plug.ex b/lib/plug.ex index 28c30f8f..4fd2da7a 100644 --- a/lib/plug.ex +++ b/lib/plug.ex @@ -81,11 +81,7 @@ defmodule Plug do 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. -<<<<<<< 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