diff options
author | Loïc Hoguin <[email protected]> | 2011-07-06 17:42:20 +0200 |
---|---|---|
committer | Loïc Hoguin <[email protected]> | 2011-07-06 17:42:20 +0200 |
commit | 108a491f5515fdc2a7fe3ce8c310a261d6be3230 (patch) | |
tree | 74fb2109c6b193c382a0712a053702b3ec240a13 /src/cowboy_tcp_transport.erl | |
parent | 2b3bfdd783915b263ed3fdfd6e135b9a84982821 (diff) | |
download | cowboy-108a491f5515fdc2a7fe3ce8c310a261d6be3230.tar.gz cowboy-108a491f5515fdc2a7fe3ce8c310a261d6be3230.tar.bz2 cowboy-108a491f5515fdc2a7fe3ce8c310a261d6be3230.zip |
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.
Diffstat (limited to 'src/cowboy_tcp_transport.erl')
-rw-r--r-- | src/cowboy_tcp_transport.erl | 41 |
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). |