Add docs

Author: wojtekmach

.gitignore

@@ -24,3 +24,4 @@ req-*.tar
 
 # Temporary files, for example, from tests.
 /tmp/
+/push.sh

README.md

@@ -1,5 +1,7 @@
 # Req
 
+<!-- MDOC !-->
+
 A work-in-progress HTTP client.
 
 # Features
@@ -129,6 +131,8 @@ def circuit_breaker(request) do
 end
 ```
 
+<!-- MDOC !-->
+
 ## License
 
 Copyright (c) 2021 Wojtek Mach

lib/req.ex

@@ -1,7 +1,15 @@
 defmodule Req do
+  @external_resource "README.md"
+
+  @moduledoc "README.md"
+             |> File.read!()
+             |> String.split("<!-- MDOC !-->")
+             |> Enum.fetch!(1)
+
   @doc """
   Makes a GET request.
   """
+  @doc api: :high_level
   def get!(url, opts \\ []) do
     case request(:get, url, opts) do
       {:ok, response} -> response
@@ -12,6 +20,7 @@ defmodule Req do
   @doc """
   Makes an HTTP request.
   """
+  @doc api: :high_level
   def request(method, url, opts \\ []) do
     method
     |> build(url, opts)
@@ -24,6 +33,7 @@ defmodule Req do
   @doc """
   Builds a request pipeline.
   """
+  @doc api: :low_level
   def build(method, url, opts \\ []) do
     body = Keyword.get(opts, :body, "")
     headers = Keyword.get(opts, :headers, [])
@@ -37,20 +47,19 @@ defmodule Req do
   end
 
   @doc """
-  Adds default steps.
-
-  This function adds the following steps:
+  Adds steps that should be reasonable defaults for most users.
 
-  * request:
+    * request:
 
-    * `default_headers/1`
+      * `default_headers/1`
 
-  * response:
+    * response:
 
-    * `decompress/2`
-    * `decode/2`
+      * `decompress/2`
+      * `decode/2`
 
   """
+  @doc api: :low_level
   def add_default_steps(request) do
     request
     |> add_request_steps([
@@ -63,22 +72,25 @@ defmodule Req do
   end
 
   @doc """
-  Adds a request step.
+  Adds request steps.
   """
+  @doc api: :low_level
   def add_request_steps(request, steps) do
     update_in(request.request_steps, &(&1 ++ steps))
   end
 
   @doc """
-  Adds a response step.
+  Adds response steps.
   """
+  @doc api: :low_level
   def add_response_steps(request, steps) do
     update_in(request.response_steps, &(&1 ++ steps))
   end
 
   @doc """
-  Adds an error step.
+  Adds error steps.
   """
+  @doc api: :low_level
   def add_error_steps(request, steps) do
     update_in(request.error_steps, &(&1 ++ steps))
   end
@@ -88,6 +100,7 @@ defmodule Req do
 
   Returns `{:ok, response}` or `{:error, exception}`.
   """
+  @doc api: :low_level
   def run(request) do
     result =
       Enum.reduce_while(request.request_steps, request, fn step, acc ->
@@ -130,10 +143,11 @@ defmodule Req do
   end
 
   @doc """
-  Runs a request pipeline.
+  Runs a request pipeline and returns a response or raises an error.
 
-  Similar to `run/1` but returns a response or raises an exception.
+  See `run/1`.
   """
+  @doc api: :low_level
   def run!(request) do
     case run(request) do
       {:ok, response} -> response
@@ -189,15 +203,27 @@ defmodule Req do
 
   ## Request steps
 
+  @user_agent "req/#{Mix.Project.config()[:version]}"
+
+  @doc """
+  Adds common request headers.
+
+  Currently the following headers are added:
+
+    * `"user-agent"` - `#{inspect(@user_agent)}`
+
+  """
+  @doc api: :request
   def default_headers(request) do
-    put_new_header(request, "user-agent", "req/0.1.0-dev")
+    put_new_header(request, "user-agent", @user_agent)
   end
 
   ## Response steps
 
   @doc """
   Decompresses the response body based on the `content-encoding` header.
   """
+  @doc api: :response
   def decompress(request, response) do
     compression_algorithms = get_content_encoding_header(response.headers)
     {request, update_in(response.body, &decompress_body(&1, compression_algorithms))}
@@ -226,6 +252,7 @@ defmodule Req do
   @doc """
   Decodes the response body based on the `content-type` header.
   """
+  @doc api: :response
   def decode(request, response) do
     case List.keyfind(response.headers, "content-type", 0) do
       {_, "application/json" <> _} ->
@@ -255,6 +282,7 @@ defmodule Req do
     * an exception
 
   """
+  @doc api: :error
   def retry(request, %{status: status} = response) when status < 500 do
     {request, response}
   end

mix.exs

@@ -4,28 +4,41 @@ defmodule Req.MixProject do
   def project do
     [
       app: :req,
-      version: "0.1.0",
+      version: "0.1.0-dev",
       elixir: "~> 1.11",
       start_permanent: Mix.env() == :prod,
-      deps: deps()
+      deps: deps(),
+      docs: docs()
     ]
   end
 
-  # Run "mix help compile.app" to learn about applications.
   def application do
     [
       mod: {Req.Application, []},
       extra_applications: [:logger]
     ]
   end
 
-  # Run "mix help deps" to learn about dependencies.
   defp deps do
     [
       {:finch, "~> 0.6.0"},
       {:mint, github: "elixir-mint/mint", override: true},
       {:jason, "~> 1.0"},
-      {:bypass, "~> 2.1", only: :test}
+      {:bypass, "~> 2.1", only: :test},
+      {:ex_doc, ">= 0.0.0", only: :docs}
+    ]
+  end
+
+  defp docs do
+    [
+      main: "Req",
+      groups_for_functions: [
+        "High-level API": &(&1[:api] == :high_level),
+        "Low-level API": &(&1[:api] == :low_level),
+        "Request steps": &(&1[:api] == :request),
+        "Response steps": &(&1[:api] == :response),
+        "Error steps": &(&1[:api] == :error)
+      ]
     ]
   end
 end

mix.lock

@@ -4,11 +4,17 @@
   "cowboy": {:hex, :cowboy, "2.8.0", "f3dc62e35797ecd9ac1b50db74611193c29815401e53bac9a5c0577bd7bc667d", [:rebar3], [{:cowlib, "~> 2.9.1", [hex: :cowlib, repo: "hexpm", optional: false]}, {:ranch, "~> 1.7.1", [hex: :ranch, repo: "hexpm", optional: false]}], "hexpm", "4643e4fba74ac96d4d152c75803de6fad0b3fa5df354c71afdd6cbeeb15fac8a"},
   "cowboy_telemetry": {:hex, :cowboy_telemetry, "0.3.1", "ebd1a1d7aff97f27c66654e78ece187abdc646992714164380d8a041eda16754", [:rebar3], [{:cowboy, "~> 2.7", [hex: :cowboy, repo: "hexpm", optional: false]}, {:telemetry, "~> 0.4", [hex: :telemetry, repo: "hexpm", optional: false]}], "hexpm", "3a6efd3366130eab84ca372cbd4a7d3c3a97bdfcfb4911233b035d117063f0af"},
   "cowlib": {:hex, :cowlib, "2.9.1", "61a6c7c50cf07fdd24b2f45b89500bb93b6686579b069a89f88cb211e1125c78", [:rebar3], [], "hexpm", "e4175dc240a70d996156160891e1c62238ede1729e45740bdd38064dad476170"},
+  "earmark_parser": {:hex, :earmark_parser, "1.4.12", "b245e875ec0a311a342320da0551da407d9d2b65d98f7a9597ae078615af3449", [:mix], [], "hexpm", "711e2cc4d64abb7d566d43f54b78f7dc129308a63bc103fbd88550d2174b3160"},
+  "ex_doc": {:hex, :ex_doc, "0.24.1", "15673de99154f93ca7f05900e4e4155ced1ee0cd34e0caeee567900a616871a4", [:mix], [{:earmark_parser, "~> 1.4.0", [hex: :earmark_parser, repo: "hexpm", optional: false]}, {:makeup_elixir, "~> 0.14", [hex: :makeup_elixir, repo: "hexpm", optional: false]}, {:makeup_erlang, "~> 0.1", [hex: :makeup_erlang, repo: "hexpm", optional: false]}], "hexpm", "07972f17bdf7dc7b5bd76ec97b556b26178ed3f056e7ec9288eb7cea7f91cce2"},
   "finch": {:hex, :finch, "0.6.3", "18b993653f5d7d5550b0a3c3f9777269b2b99db02726ac6fe776d58c2dd1a0a0", [:mix], [{:castore, "~> 0.1", [hex: :castore, repo: "hexpm", optional: false]}, {:mint, "~> 1.2", [hex: :mint, repo: "hexpm", optional: false]}, {:nimble_options, "~> 0.3.5", [hex: :nimble_options, repo: "hexpm", optional: false]}, {:nimble_pool, "~> 0.2", [hex: :nimble_pool, repo: "hexpm", optional: false]}, {:telemetry, "~> 0.4", [hex: :telemetry, repo: "hexpm", optional: false]}], "hexpm", "015f48d3a43f9d2afd06ef714636545bdb017297a63bf582cac8fdcf8ae6f031"},
   "jason": {:hex, :jason, "1.2.2", "ba43e3f2709fd1aa1dce90aaabfd039d000469c05c56f0b8e31978e03fa39052", [:mix], [{:decimal, "~> 1.0 or ~> 2.0", [hex: :decimal, repo: "hexpm", optional: true]}], "hexpm", "18a228f5f0058ee183f29f9eae0805c6e59d61c3b006760668d8d18ff0d12179"},
+  "makeup": {:hex, :makeup, "1.0.5", "d5a830bc42c9800ce07dd97fa94669dfb93d3bf5fcf6ea7a0c67b2e0e4a7f26c", [:mix], [{:nimble_parsec, "~> 0.5 or ~> 1.0", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "cfa158c02d3f5c0c665d0af11512fed3fba0144cf1aadee0f2ce17747fba2ca9"},
+  "makeup_elixir": {:hex, :makeup_elixir, "0.15.1", "b5888c880d17d1cc3e598f05cdb5b5a91b7b17ac4eaf5f297cb697663a1094dd", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}, {:nimble_parsec, "~> 1.1", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "db68c173234b07ab2a07f645a5acdc117b9f99d69ebf521821d89690ae6c6ec8"},
+  "makeup_erlang": {:hex, :makeup_erlang, "0.1.1", "3fcb7f09eb9d98dc4d208f49cc955a34218fc41ff6b84df7c75b3e6e533cc65f", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}], "hexpm", "174d0809e98a4ef0b3309256cbf97101c6ec01c4ab0b23e926a9e17df2077cbb"},
   "mime": {:hex, :mime, "1.5.0", "203ef35ef3389aae6d361918bf3f952fa17a09e8e43b5aa592b93eba05d0fb8d", [:mix], [], "hexpm", "55a94c0f552249fc1a3dd9cd2d3ab9de9d3c89b559c2bd01121f824834f24746"},
   "mint": {:git, "https://github.com/elixir-mint/mint.git", "796b8db097d69ede7163acba223ab2045c2773a4", []},
   "nimble_options": {:hex, :nimble_options, "0.3.5", "a4f6820cdcb4ee444afd78635f323e58e8a5ddf2fbbe9b9d283a99f972034bae", [:mix], [], "hexpm", "f5507cc90033a8d12769522009c80aa9164af6bab245dbd4ad421d008455f1e1"},
+  "nimble_parsec": {:hex, :nimble_parsec, "1.1.0", "3a6fca1550363552e54c216debb6a9e95bd8d32348938e13de5eda962c0d7f89", [:mix], [], "hexpm", "08eb32d66b706e913ff748f11694b17981c0b04a33ef470e33e11b3d3ac8f54b"},
   "nimble_pool": {:hex, :nimble_pool, "0.2.4", "1db8e9f8a53d967d595e0b32a17030cdb6c0dc4a451b8ac787bf601d3f7704c3", [:mix], [], "hexpm", "367e8071e137b787764e6a9992ccb57b276dc2282535f767a07d881951ebeac6"},
   "plug": {:hex, :plug, "1.11.1", "f2992bac66fdae679453c9e86134a4201f6f43a687d8ff1cd1b2862d53c80259", [:mix], [{:mime, "~> 1.0", [hex: :mime, repo: "hexpm", optional: false]}, {:plug_crypto, "~> 1.1.1 or ~> 1.2", [hex: :plug_crypto, repo: "hexpm", optional: false]}, {:telemetry, "~> 0.4", [hex: :telemetry, repo: "hexpm", optional: false]}], "hexpm", "23524e4fefbb587c11f0833b3910bfb414bf2e2534d61928e920f54e3a1b881f"},
   "plug_cowboy": {:hex, :plug_cowboy, "2.4.1", "779ba386c0915027f22e14a48919a9545714f849505fa15af2631a0d298abf0f", [:mix], [{:cowboy, "~> 2.7", [hex: :cowboy, repo: "hexpm", optional: false]}, {:cowboy_telemetry, "~> 0.3", [hex: :cowboy_telemetry, repo: "hexpm", optional: false]}, {:plug, "~> 1.7", [hex: :plug, repo: "hexpm", optional: false]}, {:telemetry, "~> 0.4", [hex: :telemetry, repo: "hexpm", optional: false]}], "hexpm", "d72113b6dff7b37a7d9b2a5b68892808e3a9a752f2bf7e503240945385b70507"},