Add more typespec and examples

Author: thiamsantos

README.md

@@ -87,13 +87,6 @@ the test finishes running.
 Multiple concurrent Bypass instances are supported, all will have a different unique port.  Concurrent
 requests are also supported on the same instance.
 
-In case you need to assign a specific port to a Bypass instance to listen on, you can pass the
-`port` option to `Bypass.open()`:
-
-```elixir
-bypass = Bypass.open(port: 1234)
-```
-
 > Note: `Bypass.open/0` **must not** be called in a `setup_all` blocks due to the way Bypass verifies the expectations at the end of each
 > test.
 

lib/bypass.ex

@@ -21,7 +21,25 @@ defmodule Bypass do
 
   Use the other functions in this module to declare which requests are handled
   and set expectations on the calls.
+
+  ## Options
+
+  - `port` - Optional TCP port to listen to requests
+
+  ## Examples
+
+  ```elixir
+  bypass = Bypass.open()
+  ```
+
+  Assign a specific port to a Bypass instance to listen on:
+
+  ```elixir
+  bypass = Bypass.open(port: 1234)
+  ```
+
   """
+  @spec open(Keyword.t()) :: Bypass.t() | DynamicSupervisor.on_start_child()
   def open(opts \\ []) do
     case DynamicSupervisor.start_child(Bypass.Supervisor, Bypass.Instance.child_spec(opts)) do
       {:ok, pid} ->
@@ -51,6 +69,7 @@ defmodule Bypass do
 
   Returns `:ok` on success and raises an error on failure.
   """
+  @spec verify_expectations!(Bypass.t()) :: :ok | no_return()
   def verify_expectations!(bypass) do
     verify_expectations!(test_framework(), bypass)
   end
@@ -101,13 +120,21 @@ defmodule Bypass do
   @doc """
   Re-opens the TCP socket on the same port. Blocks until the operation is
   complete.
+
+  ```elixir
+  Bypass.up(bypass)
+  ```
   """
   @spec up(Bypass.t()) :: :ok | {:error, :already_up}
   def up(%Bypass{pid: pid}),
     do: Bypass.Instance.call(pid, :up)
 
   @doc """
   Closes the TCP socket. Blocks until the operation is complete.
+
+  ```elixir
+  Bypass.down(bypass)
+  ```
   """
   @spec down(Bypass.t()) :: :ok | {:error, :already_down}
   def down(%Bypass{pid: pid}),
@@ -157,7 +184,7 @@ defmodule Bypass do
   end)
   ```
   """
-  @spec expect(Bypass.t(), (Plug.Conn.t() -> Plug.Conn.t())) :: :ok
+  @spec expect_once(Bypass.t(), (Plug.Conn.t() -> Plug.Conn.t())) :: :ok
   def expect_once(%Bypass{pid: pid}, fun),
     do: Bypass.Instance.call(pid, {:expect_once, fun})