chore: improve middleware docs (#721)

lib/tesla/middleware/base_url.ex

@@ -7,17 +7,26 @@ defmodule Tesla.Middleware.BaseUrl do
 
   ## Examples
 
-  ```
+  ```elixir
   defmodule MyClient do
-    use Tesla
-
-    plug Tesla.Middleware.BaseUrl, "https://example.com/foo"
+    def client do
+      Tesla.client([Tesla.Middleware.BaseUrl, "https://example.com/foo"])
+    end
   end
 
-  MyClient.get("/path") # equals to GET https://example.com/foo/path
-  MyClient.get("path") # equals to GET https://example.com/foo/path
-  MyClient.get("") # equals to GET https://example.com/foo
-  MyClient.get("http://example.com/bar") # equals to GET http://example.com/bar
+  client = MyClient.client()
+
+  Tesla.get(client, "/path")
+  # equals to GET https://example.com/foo/path
+
+  Tesla.get(client, "path")
+  # equals to GET https://example.com/foo/path
+
+  Tesla.get(client, "")
+  # equals to GET https://example.com/foo
+
+  Tesla.get(client, "http://example.com/bar")
+  # equals to GET http://example.com/bar
   ```
   """
 

lib/tesla/middleware/basic_auth.ex

@@ -6,15 +6,9 @@ defmodule Tesla.Middleware.BasicAuth do
 
   ## Examples
 
-  ```
+  ```elixir
   defmodule MyClient do
-    use Tesla
-
-    # static configuration
-    plug Tesla.Middleware.BasicAuth, username: "user", password: "pass"
-
-    # dynamic user & pass
-    def new(username, password, opts \\\\ %{}) do
+    def client(username, password, opts \\ %{}) do
       Tesla.client [
         {Tesla.Middleware.BasicAuth, Map.merge(%{username: username, password: password}, opts)}
       ]

lib/tesla/middleware/bearer_auth.ex

@@ -8,12 +8,6 @@ defmodule Tesla.Middleware.BearerAuth do
 
   ```
   defmodule MyClient do
-    use Tesla
-
-    # static configuration
-    plug Tesla.Middleware.BearerAuth, token: "token"
-
-    # dynamic token
     def new(token) do
       Tesla.client [
         {Tesla.Middleware.BearerAuth, token: token}

lib/tesla/middleware/compression.ex

@@ -6,11 +6,11 @@ defmodule Tesla.Middleware.Compression do
 
   ## Examples
 
-  ```
+  ```elixir
   defmodule MyClient do
-    use Tesla
-
-    plug Tesla.Middleware.Compression, format: "gzip"
+    def client do
+      Tesla.client([Tesla.Middleware.Compression, format: "gzip"])
+    end
   end
   ```
 

lib/tesla/middleware/decode_rels.ex

@@ -4,14 +4,16 @@ defmodule Tesla.Middleware.DecodeRels do
 
   ## Examples
 
-  ```
+  ```elixir
   defmodule MyClient do
-    use Tesla
-
-    plug Tesla.Middleware.DecodeRels
+    def client do
+      Tesla.client([Tesla.Middleware.DecodeRels])
+    end
   end
 
-  env = MyClient.get("/...")
+  client = MyClient.client()
+
+  env = Tesla.get(client, "/...")
 
   env.opts[:rels]
   # => %{"Next" => "http://...", "Prev" => "..."}

lib/tesla/middleware/digest_auth.ex

@@ -11,8 +11,6 @@ defmodule Tesla.Middleware.DigestAuth do
 
   ```
   defmodule MyClient do
-    use Tesla
-
     def client(username, password, opts \\ %{}) do
       Tesla.client([
         {Tesla.Middleware.DigestAuth, Map.merge(%{username: username, password: password}, opts)}
@@ -22,6 +20,7 @@ defmodule Tesla.Middleware.DigestAuth do
   ```
 
   ## Options
+
   - `:username` - username (defaults to `""`)
   - `:password` - password (defaults to `""`)
   - `:cnonce_fn` - custom function generating client nonce (defaults to `&Tesla.Middleware.DigestAuth.cnonce/0`)

lib/tesla/middleware/follow_redirects.ex

@@ -4,11 +4,12 @@ defmodule Tesla.Middleware.FollowRedirects do
 
   ## Examples
 
-  ```
+  ```elixir
   defmodule MyClient do
-    use Tesla
-
-    plug Tesla.Middleware.FollowRedirects, max_redirects: 3 # defaults to 5
+    def client do
+    # defaults to 5
+      Tesla.client([Tesla.Middleware.FollowRedirects, max_redirects: 3])
+    end
   end
   ```
 

lib/tesla/middleware/form_urlencoded.ex

@@ -11,11 +11,11 @@ defmodule Tesla.Middleware.FormUrlencoded do
 
   ## Examples
 
-  ```
+  ```elixir
   defmodule Myclient do
-    use Tesla
-
-    plug Tesla.Middleware.FormUrlencoded
+    def client do
+      Tesla.client([Tesla.Middleware.FormUrlencoded])
+    end
   end
 
   Myclient.post("/url", %{key: :value})
@@ -33,13 +33,15 @@ defmodule Tesla.Middleware.FormUrlencoded do
   Support for this specific case is obtained by configuring the middleware to
   encode (and decode) with `Plug.Conn.Query`
 
-  ```
+  ```elixir
   defmodule Myclient do
-    use Tesla
-
-    plug Tesla.Middleware.FormUrlencoded,
-      encode: &Plug.Conn.Query.encode/1,
-      decode: &Plug.Conn.Query.decode/1
+    def client do
+      Tesla.client([
+        Tesla.Middleware.FormUrlencoded,
+        encode: &Plug.Conn.Query.encode/1,
+        decode: &Plug.Conn.Query.decode/1
+      ])
+    end
   end
 
   Myclient.post("/url", %{key: %{nested: "value"}})

lib/tesla/middleware/fuse.ex

@@ -13,19 +13,21 @@ if Code.ensure_loaded?(:fuse) do
 
     ## Examples
 
-    ```
+    ```elixir
     defmodule MyClient do
-      use Tesla
-
-      plug Tesla.Middleware.Fuse,
-        opts: {{:standard, 2, 10_000}, {:reset, 60_000}},
-        keep_original_error: true,
-        should_melt: fn
-          {:ok, %{status: status}} when status in [428, 500, 504] -> true
-          {:ok, _} -> false
-          {:error, _} -> true
-        end,
-        mode: :sync
+      def client do
+        Tesla.client([
+          Tesla.Middleware.Fuse,
+          opts: {{:standard, 2, 10_000}, {:reset, 60_000}},
+          keep_original_error: true,
+          should_melt: fn
+            {:ok, %{status: status}} when status in [428, 500, 504] -> true
+            {:ok, _} -> false
+            {:error, _} -> true
+          end,
+          mode: :sync
+        ])
+      end
     end
     ```
 
@@ -46,7 +48,7 @@ if Code.ensure_loaded?(:fuse) do
 
     You can disable its logger output using:
 
-    ```
+    ```elixir
     config :sasl, sasl_error_logger: :false
     ```
 

lib/tesla/middleware/headers.ex

@@ -4,11 +4,11 @@ defmodule Tesla.Middleware.Headers do
 
   ## Examples
 
-  ```
+  ```elixir
   defmodule Myclient do
-    use Tesla
-
-    plug Tesla.Middleware.Headers, [{"user-agent", "Tesla"}]
+    def client do
+      Tesla.client([Tesla.Middleware.Headers, [{"user-agent", "Tesla"}]])
+    end
   end
   ```
   """

lib/tesla/middleware/json.ex

@@ -19,15 +19,18 @@ defmodule Tesla.Middleware.JSON do
 
   ```
   defmodule MyClient do
-    use Tesla
-
-    plug Tesla.Middleware.JSON # use jason engine
-    # or
-    plug Tesla.Middleware.JSON, engine: JSX, engine_opts: [strict: [:comments]]
-    # or
-    plug Tesla.Middleware.JSON, engine: Poison, engine_opts: [keys: :atoms]
-    # or
-    plug Tesla.Middleware.JSON, decode: &JSX.decode/1, encode: &JSX.encode/1
+    def client do
+      Tesla.client([
+        # use jason engine
+        Tesla.Middleware.JSON,
+        # or
+        Tesla.Middleware.JSON, engine: JSX, engine_opts: [strict: [:comments]],
+        # or
+        Tesla.Middleware.JSON, engine: Poison, engine_opts: [keys: :atoms],
+        # or
+        Tesla.Middleware.JSON, decode: &JSX.decode/1, encode: &JSX.encode/1
+      ])
+    end
   end
   ```
 

lib/tesla/middleware/keep_request.ex

@@ -6,13 +6,16 @@ defmodule Tesla.Middleware.KeepRequest do
 
   ```
   defmodule MyClient do
-    use Tesla
-
-    plug Tesla.Middleware.KeepRequest
-    plug Tesla.Middleware.PathParams
+    def client do
+      Tesla.client([
+        Tesla.Middleware.KeepRequest,
+        Tesla.Middleware.PathParams
+      ])
+    end
   end
 
-  {:ok, env} = MyClient.post("/users/:user_id", "request-data", opts: [path_params: [user_id: "1234"]])
+  client = MyClient.client()
+  {:ok, env} = Tesla.post(client, "/users/:user_id", "request-data", opts: [path_params: [user_id: "1234"]])
 
   env.body
   # => "response-data"

lib/tesla/middleware/logger.ex

@@ -62,9 +62,9 @@ defmodule Tesla.Middleware.Logger do
 
   ```elixir
   defmodule MyClient do
-    use Tesla
-
-    plug Tesla.Middleware.Logger
+    def client do
+      Tesla.client([Tesla.Middleware.Logger])
+    end
   end
   ```
 
@@ -80,7 +80,7 @@ defmodule Tesla.Middleware.Logger do
   The default log format is `"$method $url -> $status ($time ms)"`
   which shows in logs like:
 
-  ```
+  ```elixir
   2018-03-25 18:32:40.397 [info]  GET https://bitebot.io -> 200 (88.074 ms)
   ```
 
@@ -116,9 +116,9 @@ defmodule Tesla.Middleware.Logger do
 
   ```elixir
   defmodule MyClient do
-    use Tesla
-
-    plug Tesla.Middleware.Logger, log_level: &my_log_level/1
+    def client do
+      Tesla.client([Tesla.Middleware.Logger, log_level: &my_log_level/1])
+    end
 
     def my_log_level(env) do
       case env.status do
@@ -138,15 +138,15 @@ defmodule Tesla.Middleware.Logger do
   but keep the `:debug` log level (i.e. in development)
   you can set `debug: false` in your config:
 
-  ```
+  ```elixir
   # config/dev.local.exs
   config :tesla, Tesla.Middleware.Logger, debug: false
   ```
 
   Note that the logging configuration is evaluated at compile time,
   so Tesla must be recompiled for the configuration to take effect:
 
-  ```
+  ```shell
   mix deps.clean --build tesla
   mix deps.compile tesla
   ```
@@ -171,7 +171,7 @@ defmodule Tesla.Middleware.Logger do
   debug logs, add them to the `:filter_headers` option.
   `:filter_headers` expects a list of header names as strings.
 
-  ```
+  ```elixir
   # config/dev.local.exs
   config :tesla, Tesla.Middleware.Logger,
     filter_headers: ["authorization"]

lib/tesla/middleware/message_pack.ex

@@ -8,7 +8,7 @@ if Code.ensure_loaded?(Msgpax) do
     Remember to add `{:msgpax, ">= 2.3.0"}` to dependencies.
     Also, you need to recompile Tesla after adding `:msgpax` dependency:
 
-    ```
+    ```shell
     mix deps.clean tesla
     mix deps.compile tesla
     ```
@@ -19,11 +19,15 @@ if Code.ensure_loaded?(Msgpax) do
     defmodule MyClient do
       use Tesla
 
-      plug Tesla.Middleware.MessagePack
-      # or
-      plug Tesla.Middleware.MessagePack, engine_opts: [binary: true]
-      # or
-      plug Tesla.Middleware.MessagePack, decode: &Custom.decode/1, encode: &Custom.encode/1
+      def client do
+        Tesla.client([
+          Tesla.Middleware.MessagePack,
+          # or
+          Tesla.Middleware.MessagePack, engine_opts: [binary: true],
+          # or
+          Tesla.Middleware.MessagePack, decode: &Custom.decode/1, encode: &Custom.encode/1
+        ])
+      end
     end
     ```
 

lib/tesla/middleware/method_override.ex

@@ -7,11 +7,11 @@ defmodule Tesla.Middleware.MethodOverride do
 
   ## Examples
 
-  ```
+  ```elixir
   defmodule MyClient do
-    use Tesla
-
-    plug Tesla.Middleware.MethodOverride
+    def client do
+      Tesla.client([Tesla.Middleware.MethodOverride])
+    end
   end
   ```