Add documentation for the public interface.

This is probably not perfect yet but it should be better than
nothing. We'll improve things with feedback received from the
many users.

1 files changed, 38 insertions, 3 deletions

diff --git a/src/cowboy_tcp_transport.erl b/src/cowboy_tcp_transport.erl
index 1597b88..c1dad62 100644
--- a/src/cowboy_tcp_transport.erl
+++ b/src/cowboy_tcp_transport.erl
@@ -12,18 +12,39 @@
 %% ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 %% OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 
+%% @doc TCP transport API.
+%%
+%% Wrapper around <em>gen_tcp</em> implementing the Cowboy transport API.
+%%
+%% @see gen_tcp
 -module(cowboy_tcp_transport).
--export([name/0, messages/0, listen/1, accept/2, recv/3, send/2, setopts/2,
-	controlling_process/2, peername/1, close/1]). %% API.
 
-%% API.
+-export([name/0, messages/0, listen/1, accept/2, recv/3, send/2, setopts/2,
+	controlling_process/2, peername/1, close/1]).
 
+%% @doc Name of this transport API, <em>tcp</em>.
 -spec name() -> tcp.
 name() -> tcp.
 
+%% @doc Atoms used in the process messages sent by this API.
+%%
+%% They identify incoming data, closed connection and errors when receiving
+%% data in active mode.
 -spec messages() -> {tcp, tcp_closed, tcp_error}.
 messages() -> {tcp, tcp_closed, tcp_error}.
 
+%% @doc Setup a socket to listen on the given port on the local host.
+%%
+%% The available options are:
+%% <dl>
+%%  <dt>port</dt><dd>Mandatory. TCP port number to open.</dd>
+%%  <dt>backlog</dt><dd>Maximum length of the pending connections queue.
+%%   Defaults to 1024.</dd>
+%%  <dt>ip</dt><dd>Interface to listen on. Listen on all interfaces
+%%   by default.</dd>
+%% </dl>
+%%
+%% @see gen_tcp:listen/2
 -spec listen([{port, inet:ip_port()} | {ip, inet:ip_address()}])
 	-> {ok, inet:socket()} | {error, atom()}.
 listen(Opts) ->
@@ -38,34 +59,48 @@ listen(Opts) ->
 		end,
 	gen_tcp:listen(Port, ListenOpts).
 
+%% @doc Accept an incoming connection on a listen socket.
+%% @see gen_tcp:accept/2
 -spec accept(inet:socket(), timeout())
 	-> {ok, inet:socket()} | {error, closed | timeout | atom()}.
 accept(LSocket, Timeout) ->
 	gen_tcp:accept(LSocket, Timeout).
 
+%% @doc Receive a packet from a socket in passive mode.
+%% @see gen_tcp:recv/3
 -spec recv(inet:socket(), non_neg_integer(), timeout())
 	-> {ok, any()} | {error, closed | atom()}.
 recv(Socket, Length, Timeout) ->
 	gen_tcp:recv(Socket, Length, Timeout).
 
+%% @doc Send a packet on a socket.
+%% @see gen_tcp:send/2
 -spec send(inet:socket(), iolist()) -> ok | {error, atom()}.
 send(Socket, Packet) ->
 	gen_tcp:send(Socket, Packet).
 
+%% @doc Set one or more options for a socket.
+%% @see inet:setopts/2
 -spec setopts(inet:socket(), list()) -> ok | {error, atom()}.
 setopts(Socket, Opts) ->
 	inet:setopts(Socket, Opts).
 
+%% @doc Assign a new controlling process <em>Pid</em> to <em>Socket</em>.
+%% @see gen_tcp:controlling_process/2
 -spec controlling_process(inet:socket(), pid())
 	-> ok | {error, closed | not_owner | atom()}.
 controlling_process(Socket, Pid) ->
 	gen_tcp:controlling_process(Socket, Pid).
 
+%% @doc Return the address and port for the other end of a connection.
+%% @see inet:peername/1
 -spec peername(inet:socket())
 	-> {ok, {inet:ip_address(), inet:ip_port()}} | {error, atom()}.
 peername(Socket) ->
 	inet:peername(Socket).
 
+%% @doc Close a TCP socket.
+%% @see gen_tcp:close/1
 -spec close(inet:socket()) -> ok.
 close(Socket) ->
 	gen_tcp:close(Socket).