chore: fixing example and removing reminder use Tesla showcasing (#723)

lib/tesla.ex

@@ -4,75 +4,49 @@ defmodule Tesla do
 
   ## Building API client
 
-  `use Tesla` macro will generate basic HTTP functions (e.g. `get/3`, `post/4`, etc.) inside your module.
-
-  It supports following options:
-
-  - `:only` - builder will generate only functions included in the given list
-  - `:except` - builder will not generate the functions that are listed in the options
-  - `:docs` - when set to false builder will not add documentation to generated functions
+  Use `Tesla.client/2` to build a client with the given middleware and adapter.
 
   ### Examples
 
-      defmodule ExampleApi do
-        use Tesla, only: [:get], docs: false
-
-        plug Tesla.Middleware.BaseUrl, "http://api.example.com"
-        plug Tesla.Middleware.JSON
-
-        def fetch_data do
-          get("/data")
-        end
-      end
-
-  In example above `ExampleApi.fetch_data/0` is equivalent of `ExampleApi.get("/data")`.
-
-      defmodule ExampleApi do
-        use Tesla, except: [:post, :delete]
+  ```elixir
+  defmodule ExampleApi do
+    def client do
+      Tesla.client([
+        Tesla.Middleware.BaseUrl, "http://api.example.com",
+        Tesla.Middleware.JSON
+      ])
+    end
 
-        plug Tesla.Middleware.BaseUrl, "http://api.example.com"
-        plug Tesla.Middleware.JSON
+    def fetch_data(client) do
+      Tesla.get(client, "/data")
+    end
+  end
+  ```
 
-        def fetch_data do
-          get("/data")
-        end
-      end
+  Now you can use `ExampleApi.client/0` to make requests to the API.
 
-  In example above `except: [:post, :delete]` will make sure that post functions will not be generated for this module.
+  ```elixir
+  client = ExampleApi.client()
+  ExampleApi.fetch_data(client)
+  ```
 
   ## Direct usage
 
   It is also possible to do request directly with `Tesla` module.
 
-      Tesla.get("https://example.com")
-
-  ### Common pitfalls
-
-  Direct usage won't include any middlewares.
-
-  In following example:
-
-      defmodule ExampleApi do
-        use Tesla, only: [:get], docs: false
-
-        plug Tesla.Middleware.BaseUrl, "http://api.example.com"
-        plug Tesla.Middleware.JSON
-
-        def fetch_data do
-          Tesla.get("/data")
-        end
-      end
-
-  call to `ExampleApi.fetch_data/0` will fail, because request will be missing
-  base URL.
+  ```elixir
+  Tesla.get("https://example.com")
+  ```
 
   ## Default adapter
 
   By default `Tesla` is using `Tesla.Adapter.Httpc`, because `:httpc` is
   included in Erlang/OTP and does not require installation of any additional
   dependency. It can be changed globally with config:
 
-      config :tesla, :adapter, Tesla.Adapter.Hackney
+  ```elixir
+  config :tesla, :adapter, Tesla.Adapter.Mint
+  ```
   """
 
   use Tesla.Builder
@@ -247,8 +221,6 @@ defmodule Tesla do
 
   # complete module example
   defmodule MyApi do
-    # note there is no need for `use Tesla`
-
     @middleware [
       {Tesla.Middleware.BaseUrl, "https://example.com"},
       Tesla.Middleware.JSON,

lib/tesla/middleware/base_url.ex

@@ -10,7 +10,9 @@ defmodule Tesla.Middleware.BaseUrl do
   ```elixir
   defmodule MyClient do
     def client do
-      Tesla.client([Tesla.Middleware.BaseUrl, "https://example.com/foo"])
+      Tesla.client([
+        {Tesla.Middleware.BaseUrl, "https://example.com/foo"}
+      ])
     end
   end
 

lib/tesla/middleware/basic_auth.ex

@@ -9,9 +9,10 @@ defmodule Tesla.Middleware.BasicAuth do
   ```elixir
   defmodule MyClient do
     def client(username, password, opts \\ %{}) do
-      Tesla.client [
-        {Tesla.Middleware.BasicAuth, Map.merge(%{username: username, password: password}, opts)}
-      ]
+      Tesla.client([
+        {Tesla.Middleware.BasicAuth,
+          Map.merge(%{username: username, password: password}, opts)}
+      ])
     end
   end
   ```

lib/tesla/middleware/bearer_auth.ex

@@ -9,9 +9,9 @@ defmodule Tesla.Middleware.BearerAuth do
   ```
   defmodule MyClient do
     def new(token) do
-      Tesla.client [
+      Tesla.client([
         {Tesla.Middleware.BearerAuth, token: token}
-      ]
+      ])
     end
   end
   ```

lib/tesla/middleware/compression.ex

@@ -9,7 +9,9 @@ defmodule Tesla.Middleware.Compression do
   ```elixir
   defmodule MyClient do
     def client do
-      Tesla.client([Tesla.Middleware.Compression, format: "gzip"])
+      Tesla.client([
+        {Tesla.Middleware.Compression, format: "gzip"}
+      ])
     end
   end
   ```

lib/tesla/middleware/follow_redirects.ex

@@ -8,7 +8,9 @@ defmodule Tesla.Middleware.FollowRedirects do
   defmodule MyClient do
     def client do
     # defaults to 5
-      Tesla.client([Tesla.Middleware.FollowRedirects, max_redirects: 3])
+      Tesla.client([
+        {Tesla.Middleware.FollowRedirects, max_redirects: 3}
+      ])
     end
   end
   ```

lib/tesla/middleware/form_urlencoded.ex

@@ -14,11 +14,16 @@ defmodule Tesla.Middleware.FormUrlencoded do
   ```elixir
   defmodule Myclient do
     def client do
-      Tesla.client([Tesla.Middleware.FormUrlencoded])
+      Tesla.client([
+        {Tesla.Middleware.FormUrlencoded,
+          encode: &Plug.Conn.Query.encode/1,
+          decode: &Plug.Conn.Query.decode/1}
+      ])
     end
   end
 
-  Myclient.post("/url", %{key: :value})
+  client = Myclient.client()
+  Myclient.post(client, "/url", %{key: :value})
   ```
 
   ## Options
@@ -37,14 +42,15 @@ defmodule Tesla.Middleware.FormUrlencoded do
   defmodule Myclient do
     def client do
       Tesla.client([
-        Tesla.Middleware.FormUrlencoded,
-        encode: &Plug.Conn.Query.encode/1,
-        decode: &Plug.Conn.Query.decode/1
+        {Tesla.Middleware.FormUrlencoded,
+          encode: &Plug.Conn.Query.encode/1,
+          decode: &Plug.Conn.Query.decode/1}
       ])
     end
   end
 
-  Myclient.post("/url", %{key: %{nested: "value"}})
+  client = Myclient.client()
+  Myclient.post(client, "/url", %{key: %{nested: "value"}})
   ```
   """
 

lib/tesla/middleware/fuse.ex

@@ -17,15 +17,15 @@ if Code.ensure_loaded?(:fuse) do
     defmodule MyClient do
       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
+          {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

lib/tesla/middleware/headers.ex

@@ -7,7 +7,9 @@ defmodule Tesla.Middleware.Headers do
   ```elixir
   defmodule Myclient do
     def client do
-      Tesla.client([Tesla.Middleware.Headers, [{"user-agent", "Tesla"}]])
+      Tesla.client([
+        {Tesla.Middleware.Headers, [{"user-agent", "Tesla"}]}
+      ])
     end
   end
   ```

lib/tesla/middleware/json.ex

@@ -24,11 +24,11 @@ defmodule Tesla.Middleware.JSON do
         # use jason engine
         Tesla.Middleware.JSON,
         # or
-        Tesla.Middleware.JSON, engine: JSX, engine_opts: [strict: [:comments]],
+        {Tesla.Middleware.JSON, engine: JSX, engine_opts: [strict: [:comments]]},
         # or
-        Tesla.Middleware.JSON, engine: Poison, engine_opts: [keys: :atoms],
+        {Tesla.Middleware.JSON, engine: Poison, engine_opts: [keys: :atoms]},
         # or
-        Tesla.Middleware.JSON, decode: &JSX.decode/1, encode: &JSX.encode/1
+        {Tesla.Middleware.JSON, decode: &JSX.decode/1, encode: &JSX.encode/1}
       ])
     end
   end

lib/tesla/middleware/logger.ex

@@ -94,9 +94,11 @@ defmodule Tesla.Middleware.Logger do
 
   ```elixir
   defmodule MyClient do
-    use Tesla
-
-    plug Tesla.Middleware.Logger, format: &my_format/3
+    def client do
+      Tesla.client([
+        {Tesla.Middleware.Logger, format: &my_format/3}
+      ])
+    end
 
     def my_format(request, response, time) do
       "request=#{inspect(request)} response=#{inspect(response)} time=#{time}\n"
@@ -117,7 +119,9 @@ defmodule Tesla.Middleware.Logger do
   ```elixir
   defmodule MyClient do
     def client do
-      Tesla.client([Tesla.Middleware.Logger, log_level: &my_log_level/1])
+      Tesla.client([
+        {Tesla.Middleware.Logger, log_level: &my_log_level/1}
+      ])
     end
 
     def my_log_level(env) do

lib/tesla/middleware/message_pack.ex

@@ -15,17 +15,15 @@ if Code.ensure_loaded?(Msgpax) do
 
     ## Examples
 
-    ```
+    ```elixir
     defmodule MyClient do
-      use Tesla
-
       def client do
         Tesla.client([
           Tesla.Middleware.MessagePack,
           # or
-          Tesla.Middleware.MessagePack, engine_opts: [binary: true],
+          {Tesla.Middleware.MessagePack, engine_opts: [binary: true]},
           # or
-          Tesla.Middleware.MessagePack, decode: &Custom.decode/1, encode: &Custom.encode/1
+          {Tesla.Middleware.MessagePack, decode: &Custom.decode/1, encode: &Custom.encode/1}
         ])
       end
     end

lib/tesla/middleware/opts.ex

@@ -7,7 +7,9 @@ defmodule Tesla.Middleware.Opts do
   ```elixir
   defmodule MyClient do
     def client do
-      Tesla.client([Tesla.Middleware.Opts, [some: "option"]])
+      Tesla.client([
+        {Tesla.Middleware.Opts, [some: "option"]}
+      ])
     end
   end
   ```

lib/tesla/middleware/path_params.ex

@@ -31,7 +31,7 @@ defmodule Tesla.Middleware.PathParams do
   defmodule MyClient do
     def client do
       Tesla.client([
-        Tesla.Middleware.BaseUrl, "https://api.example.com",
+        {Tesla.Middleware.BaseUrl, "https://api.example.com"},
         Tesla.Middleware.Logger,
         Tesla.Middleware.PathParams
       ])

lib/tesla/middleware/query.ex

@@ -7,7 +7,9 @@ defmodule Tesla.Middleware.Query do
   ```elixir
   defmodule MyClient do
     def client do
-      Tesla.client([Tesla.Middleware.Query, [token: "some-token"]])
+      Tesla.client([
+        {Tesla.Middleware.Query, [token: "some-token"]}
+      ])
     end
   end
   ```

lib/tesla/middleware/retry.ex

@@ -37,7 +37,6 @@ defmodule Tesla.Middleware.Retry do
             {:error, _reason}, _env, _context -> true
           end
         }
-        # or
       ])
     end
   end