Improve callback documentation (#1013)

lib/plug.ex

@@ -16,11 +16,11 @@ defmodule Plug do
   A module plug is an extension of the function plug. It is a module that must
   export:
 
-    * a `call/2` function with the signature defined above
-    * an `init/1` function which takes a set of options and initializes it.
+    * a `c:call/2` function with the signature defined above
+    * an `c:init/1` function which takes a set of options and initializes it.
 
-  The result returned by `init/1` is passed as second argument to `call/2`. Note
-  that `init/1` may be called during compilation and as such it must not return
+  The result returned by `c:init/1` is passed as second argument to `c:call/2`. Note
+  that `c:init/1` may be called during compilation and as such it must not return
   pids, ports or values that are specific to the runtime.
 
   The API expected by a module plug is defined as a behaviour by the
@@ -65,7 +65,7 @@ defmodule Plug do
           | MapSet.t()
 
   @callback init(opts) :: opts
-  @callback call(Plug.Conn.t(), opts) :: Plug.Conn.t()
+  @callback call(conn :: Plug.Conn.t(), opts) :: Plug.Conn.t()
 
   require Logger
 

lib/plug/conn/adapter.ex

@@ -24,7 +24,12 @@ defmodule Plug.Conn.Adapter do
   test implementation returns the actual body so it can
   be used during testing.
   """
-  @callback send_resp(payload, Conn.status(), Conn.headers(), Conn.body()) ::
+  @callback send_resp(
+              payload,
+              status :: Conn.status(),
+              headers :: Conn.headers(),
+              body :: Conn.body()
+            ) ::
               {:ok, sent_body :: binary | nil, payload}
 
   @doc """
@@ -41,8 +46,8 @@ defmodule Plug.Conn.Adapter do
   """
   @callback send_file(
               payload,
-              Conn.status(),
-              Conn.headers(),
+              status :: Conn.status(),
+              headers :: Conn.headers(),
               file :: binary,
               offset :: integer,
               length :: integer | :all
@@ -57,7 +62,7 @@ defmodule Plug.Conn.Adapter do
   test implementation returns the actual body so it can
   be used during testing.
   """
-  @callback send_chunked(payload, Conn.status(), Conn.headers()) ::
+  @callback send_chunked(payload, status :: Conn.status(), headers :: Conn.headers()) ::
               {:ok, sent_body :: binary | nil, payload}
 
   @doc """
@@ -71,7 +76,7 @@ defmodule Plug.Conn.Adapter do
   implementation returns the actual body and payload so
   it can be used during testing.
   """
-  @callback chunk(payload, Conn.body()) ::
+  @callback chunk(payload, body :: Conn.body()) ::
               :ok | {:ok, sent_body :: binary, payload} | {:error, term}
 
   @doc """
@@ -99,7 +104,8 @@ defmodule Plug.Conn.Adapter do
   If the adapter does not support inform, then `{:error, :not_supported}`
   should be returned.
   """
-  @callback inform(payload, Conn.status(), headers :: Keyword.t()) :: :ok | {:error, term}
+  @callback inform(payload, status :: Conn.status(), headers :: Keyword.t()) ::
+              :ok | {:error, term}
 
   @doc """
   Returns peer information such as the address, port and ssl cert.

lib/plug/session/store.ex

@@ -41,9 +41,9 @@ defmodule Plug.Session.Store do
   Initializes the store.
 
   The options returned from this function will be given
-  to `get/3`, `put/4` and `delete/3`.
+  to `c:get/3`, `c:put/4` and `c:delete/3`.
   """
-  @callback init(Plug.opts()) :: Plug.opts()
+  @callback init(opts :: Plug.opts()) :: Plug.opts()
 
   @doc """
   Parses the given cookie.
@@ -54,18 +54,18 @@ defmodule Plug.Session.Store do
   The session id may be nil in case the cookie does not identify any
   value in the store. The session contents must be a map.
   """
-  @callback get(Plug.Conn.t(), cookie, Plug.opts()) :: {sid, session}
+  @callback get(conn :: Plug.Conn.t(), cookie, opts :: Plug.opts()) :: {sid, session}
 
   @doc """
   Stores the session associated with given session id.
 
   If `nil` is given as id, a new session id should be
   generated and returned.
   """
-  @callback put(Plug.Conn.t(), sid, any, Plug.opts()) :: cookie
+  @callback put(conn :: Plug.Conn.t(), sid, any, opts :: Plug.opts()) :: cookie
 
   @doc """
   Removes the session associated with given session id from the store.
   """
-  @callback delete(Plug.Conn.t(), sid, Plug.opts()) :: :ok
+  @callback delete(conn :: Plug.Conn.t(), sid, opts :: Plug.opts()) :: :ok
 end