Merge pull request #446 from kianmeng/misc-doc-changes

.gitignore

@@ -1,9 +1,23 @@
-/_build
-/deps
+# The directory Mix will write compiled artifacts to.
+/_build/
+
+# If you run "mix test --cover", coverage assets end up here.
+/cover/
+
+# The directory Mix downloads your dependencies sources to.
+/deps/
+
+# Where third-party dependencies like ExDoc output generated docs.
+/doc/
+
+# If the VM crashes, it generates a dump, let's ignore it too.
 erl_crash.dump
+
+# Also ignore archive artifacts (built via "mix archive.build").
 *.ez
-/doc
-/cover
-.tool-versions
-/sandbox
-.elixir_ls
+
+# Ignore package tarball (built via "mix hex.build").
+tesla-*.tar
+
+# Temporary files for e.g. tests
+/tmp

LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2015-2020 Tymon Tobolski
+Copyright (c) 2015-2021 Tymon Tobolski
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -2,6 +2,7 @@
 
 [![Build Status](https://github.com/teamon/tesla/workflows/Test/badge.svg?branch=master)](https://github.com/teamon/tesla/actions)
 [![Hex.pm](https://img.shields.io/hexpm/v/tesla.svg)](http://hex.pm/packages/tesla)
+[![Hexdocs.pm](https://img.shields.io/badge/hex-docs-lightgreen.svg)](https://hexdocs.pm/tesla/)
 [![Hex.pm](https://img.shields.io/hexpm/dt/tesla.svg)](https://hex.pm/packages/tesla)
 [![Hex.pm](https://img.shields.io/hexpm/dw/tesla.svg)](https://hex.pm/packages/tesla)
 [![codecov](https://codecov.io/gh/teamon/tesla/branch/master/graph/badge.svg)](https://codecov.io/gh/teamon/tesla)
@@ -14,11 +15,7 @@ It embraces the concept of middleware when processing the request/response cycle
   released version on Hex. See [the documentation](http://hexdocs.pm/tesla) for
   the documentation of the version you're using.
 
----
-
-## [`0.x` to `1.0` Migration Guide](https://github.com/teamon/tesla/wiki/0.x-to-1.0-Migration-Guide)
-
-[Documentation for 0.x branch](https://github.com/teamon/tesla/tree/0.x)
+For the list of changes, checkout the latest [release notes](https://github.com/teamon/tesla/releases).
 
 ---
 
@@ -59,7 +56,7 @@ See below for documentation.
 
 ## Installation
 
-Add `tesla` as dependency in `mix.exs`:
+Add `:tesla` as dependency in `mix.exs`:
 
 ```elixir
 defp deps do
@@ -73,7 +70,6 @@ defp deps do
     {:jason, ">= 1.0.0"}
   ]
 end
-
 ```
 
 Tesla uses [Semantic Versioning](https://semver.org) 2.0.
@@ -115,17 +111,17 @@ This is very similar to how [Plug Router](https://github.com/elixir-plug/plug#th
 - [`Tesla.Middleware.Headers`](https://hexdocs.pm/tesla/Tesla.Middleware.Headers.html) - set request headers
 - [`Tesla.Middleware.Query`](https://hexdocs.pm/tesla/Tesla.Middleware.Query.html) - set query parameters
 - [`Tesla.Middleware.Opts`](https://hexdocs.pm/tesla/Tesla.Middleware.Opts.html) - set request options
-- [`Tesla.Middleware.FollowRedirects`](https://hexdocs.pm/tesla/Tesla.Middleware.FollowRedirects.html) - follow 3xx redirects
-- [`Tesla.Middleware.MethodOverride`](https://hexdocs.pm/tesla/Tesla.Middleware.MethodOverride.html) - set X-Http-Method-Override
-- [`Tesla.Middleware.Logger`](https://hexdocs.pm/tesla/Tesla.Middleware.Logger.html) - log requests (method, url, status, time)
-- [`Tesla.Middleware.KeepRequest`](https://hexdocs.pm/tesla/Tesla.Middleware.KeepRequest.html) - keep request body & headers
+- [`Tesla.Middleware.FollowRedirects`](https://hexdocs.pm/tesla/Tesla.Middleware.FollowRedirects.html) - follow HTTP 3xx redirects
+- [`Tesla.Middleware.MethodOverride`](https://hexdocs.pm/tesla/Tesla.Middleware.MethodOverride.html) - set `X-Http-Method-Override` header
+- [`Tesla.Middleware.Logger`](https://hexdocs.pm/tesla/Tesla.Middleware.Logger.html) - log requests (method, url, status, and time)
+- [`Tesla.Middleware.KeepRequest`](https://hexdocs.pm/tesla/Tesla.Middleware.KeepRequest.html) - keep request `body` and `headers`
 - [`Tesla.Middleware.PathParams`](https://hexdocs.pm/tesla/Tesla.Middleware.PathParams.html) - use templated URLs
 
 ### Formats
 
 - [`Tesla.Middleware.FormUrlencoded`](https://hexdocs.pm/tesla/Tesla.Middleware.FormUrlencoded.html) - urlencode POST body, useful for POSTing a map/keyword list
 - [`Tesla.Middleware.JSON`](https://hexdocs.pm/tesla/Tesla.Middleware.JSON.html) - JSON request/response body
-- [`Tesla.Middleware.Compression`](https://hexdocs.pm/tesla/Tesla.Middleware.Compression.html) - gzip & deflate
+- [`Tesla.Middleware.Compression`](https://hexdocs.pm/tesla/Tesla.Middleware.Compression.html) - `gzip` and `deflate`
 - [`Tesla.Middleware.DecodeRels`](https://hexdocs.pm/tesla/Tesla.Middleware.DecodeRels.html) - decode `Link` header into `opts[:rels]` field in response
 
 ### Auth
@@ -141,7 +137,7 @@ This is very similar to how [Plug Router](https://github.com/elixir-plug/plug#th
 
 ## Runtime middleware
 
-All HTTP functions (`get`, `post`, etc.) can take a dynamic client as the first argument.
+All HTTP functions, such as `Tesla.get/3` and `Tesla.post/4`, can take a dynamic client as the first argument.
 This allow to use convenient syntax for modifying the behaviour in runtime.
 
 Consider the following case: GitHub API can be accessed using OAuth token authorization.
@@ -196,13 +192,14 @@ Tesla supports multiple HTTP adapter that do the actual HTTP request processing.
 - [`Tesla.Adapter.Mint`](https://hexdocs.pm/tesla/Tesla.Adapter.Mint.html) - [mint](https://github.com/elixir-mint/mint), "Functional HTTP client for Elixir with support for HTTP/1 and HTTP/2"
 - [`Tesla.Adapter.Finch`](https://hexdocs.pm/tesla/Tesla.Adapter.Finch.html) - [finch](https://github.com/keathley/finch), "An HTTP client with a focus on performance, built on top of [Mint](https://github.com/elixir-mint/mint) and [NimblePool](https://github.com/dashbitco/nimble_pool)."
 
-When using adapter other than httpc remember to add it to the dependencies list in `mix.exs`
+When using adapter other than `:httpc` remember to add it to the dependencies list in `mix.exs`
 
 ```elixir
 defp deps do
-  [{:tesla, "~> 1.4.0"},
-   {:jason, ">= 1.0.0"}, # optional, required by JSON middleware
-   {:hackney, "~> 1.10"}] # or :gun etc.
+  [
+    {:tesla, "~> 1.4.0"},
+    {:hackney, "~> 1.10"} # when using hackney adapter
+  ]
 end
 ```
 
@@ -230,7 +227,7 @@ def new(...) do
 end
 ```
 
-Passing directly to `get`/`post`/etc.
+Passing directly to request functions such as `MyClient.get/3` or `Tesla.get/3`.
 
 ```elixir
 MyClient.get("/", opts: [adapter: [recv_timeout: 30_000]])
@@ -255,11 +252,11 @@ defmodule ElasticSearch do
 end
 ```
 
-Each piece of stream will be encoded as JSON and sent as a new line (conforming to JSON stream format)
+Each piece of stream will be encoded as JSON and sent as a new line (conforming to JSON stream format).
 
 ## Multipart
 
-You can pass a `Tesla.Multipart` struct as the body.
+You can pass a `Tesla.Multipart` struct as the body:
 
 ```elixir
 alias Tesla.Multipart
@@ -280,7 +277,7 @@ mp =
 
 ## Testing
 
-You can set the adapter to `Tesla.Mock` in tests.
+You can set the adapter to `Tesla.Mock` in tests:
 
 ```elixir
 # config/test.exs
@@ -320,8 +317,7 @@ end
 
 ## Writing middleware
 
-A Tesla middleware is a module with `c:Tesla.Middleware.call/3` function, that at some point calls `Tesla.run/2` with `env` and `next` to process
-the rest of stack.
+A Tesla middleware is a module with `c:Tesla.Middleware.call/3` function, that at some point calls `Tesla.run/2` with `env` and `next` to process the rest of stack.
 
 ```elixir
 defmodule MyMiddleware do
@@ -384,7 +380,7 @@ defmodule Tesla.Middleware.SomeMiddleware do
   Longer description, including e.g. additional dependencies.
 
 
-  ### Example usage
+  ### Examples
 
   ```
   defmodule MyClient do
@@ -503,6 +499,10 @@ defmodule Tesla.Middleware.MyCustomMiddleware do
 end
 ```
 
+## [`0.x` to `1.0` Migration Guide](https://github.com/teamon/tesla/wiki/0.x-to-1.0-Migration-Guide)
+
+[Documentation for 0.x branch](https://github.com/teamon/tesla/tree/0.x)
+
 ## Contributing
 
 1. Fork it (https://github.com/teamon/tesla/fork)
@@ -515,7 +515,7 @@ end
 
 This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details
 
-Copyright (c) 2015-2020 [Tymon Tobolski](https://teamon.me/about/)
+Copyright (c) 2015-2021 [Tymon Tobolski](https://teamon.me/about/)
 
 ---
 

lib/tesla.ex

@@ -66,7 +66,7 @@ end
 
 defmodule Tesla.Middleware do
   @moduledoc """
-  The middleware specification
+  The middleware specification.
 
   Middleware is an extension of basic `Tesla` functionality. It is a module that must
   implement `c:Tesla.Middleware.call/3`.
@@ -77,7 +77,7 @@ defmodule Tesla.Middleware do
 
       plug Tesla.Middleware.BaseUrl, "https://example.com"
 
-  or inside tuple in case of dynamic middleware (`Tesla.client/1`)
+  or inside tuple in case of dynamic middleware (`Tesla.client/1`):
 
       Tesla.client([{Tesla.Middleware.BaseUrl, "https://example.com"}])
 
@@ -87,7 +87,7 @@ defmodule Tesla.Middleware do
 
   See `c:Tesla.Middleware.call/3` for details.
 
-  ### Example
+  ### Examples
 
       defmodule MyProject.InspectHeadersMiddleware do
         @behaviour Tesla.Middleware
@@ -138,7 +138,7 @@ defmodule Tesla.Adapter do
 
   See `c:Tesla.Adapter.call/2` for details.
 
-  ### Example
+  ### Examples
 
       defmodule MyProject.CustomAdapter do
         alias Tesla.Multipart
@@ -215,18 +215,19 @@ defmodule Tesla do
   @default_adapter Tesla.Adapter.Httpc
 
   @moduledoc """
-  A HTTP toolkit for building API clients using middlewares
+  A HTTP toolkit for building API clients using middlewares.
 
   ## Building API client
 
-  `use Tesla` macro will generate basic http functions (e.g. get, post) inside your module.
+  `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
 
-  ### Example
+  ### Examples
 
       defmodule ExampleApi do
         use Tesla, only: [:get], docs: false
@@ -277,16 +278,16 @@ defmodule Tesla do
         end
       end
 
-  call to `ExampleApi.fetch_data/0` will fail, because request will be missing base url.
+  call to `ExampleApi.fetch_data/0` will fail, because request will be missing base URL.
 
   ## Default adapter
 
   By default `Tesla` is using `Tesla.Adapter.Httpc`, because `:httpc` is included in Erlang/OTP and
-  doen not require installation of any additional dependency. It can be changed globally with config
+  does not require installation of any additional dependency. It can be changed globally with config:
 
       config :tesla, :adapter, Tesla.Adapter.Hackney
 
-  or by `Tesla.Builder.adapter/2` macro for given API client module
+  or by `Tesla.Builder.adapter/2` macro for given API client module:
 
       defmodule ExampleApi do
         use Tesla
@@ -380,7 +381,7 @@ defmodule Tesla do
 
   Useful when there's need to store additional middleware data in `Tesla.Env`
 
-  ## Example
+  ## Examples
 
       iex> %Tesla.Env{opts: []} |> Tesla.put_opt(:option, "value")
       %Tesla.Env{opts: [option: "value"]}
@@ -509,7 +510,7 @@ defmodule Tesla do
 
   Useful when you need to create an URL with dynamic query params from a Keyword list
 
-  ## Example
+  ## Examples
 
       iex> Tesla.build_url("http://api.example.com", [user: 3, page: 2])
       "http://api.example.com?user=3&page=2"

lib/tesla/adapter/finch.ex

@@ -11,7 +11,7 @@ if Code.ensure_loaded?(Finch) do
     mix compile
     ```
 
-    ## Example usage
+    ## Examples
 
     In order to use Finch, you must start it and provide a `:name`. For example,
     in your supervision tree:
@@ -43,10 +43,10 @@ if Code.ensure_loaded?(Finch) do
     ## [Finch options](https://hexdocs.pm/finch/Finch.html#request/3)
 
       * `:pool_timeout` - This timeout is applied when a connection is checekd
-      out from the pool. Default value is `5_000`.
+        out from the pool. Default value is `5_000`.
 
       * `:receive_timeout` - The maximum time to wait for a response before
-      returning an error. Default value is `15_000`.
+        returning an error. Default value is `15_000`.
 
     """
     @behaviour Tesla.Adapter