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, 54 insertions, 3 deletions

diff --git a/src/cowboy_ssl_transport.erl b/src/cowboy_ssl_transport.erl
index 8e569ec..098d409 100644
--- a/src/cowboy_ssl_transport.erl
+++ b/src/cowboy_ssl_transport.erl
@@ -12,18 +12,50 @@
 %% ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 %% OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 
+%% @doc SSL transport API.
+%%
+%% Wrapper around <em>ssl</em> implementing the Cowboy transport API.
+%%
+%% This transport requires the <em>crypto</em>, <em>public_key</em>
+%% and <em>ssl</em> applications to be started. If they aren't started,
+%% it will try to start them itself before opening a port to listen.
+%% Applications aren't stopped when the listening socket is closed, though.
+%%
+%% @see ssl
 -module(cowboy_ssl_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.
+	controlling_process/2, peername/1, close/1]).
 
+%% @doc Name of this transport API, <em>ssl</em>.
 -spec name() -> ssl.
 name() -> ssl.
 
+%% @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() -> {ssl, ssl_closed, ssl_error}.
 messages() -> {ssl, ssl_closed, ssl_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>
+%%  <dt>certfile</dt><dd>Mandatory. Path to a file containing the user's
+%%   certificate.</dd>
+%%  <dt>keyfile</dt><dd>Mandatory. Path to the file containing the user's
+%%   private PEM encoded key.</dd>
+%%  <dt>password</dt><dd>Mandatory. String containing the user's password.
+%%   All private keyfiles must be password protected currently.</dd>
+%% </dl>
+%%
+%% @see ssl:listen/2
+%% @todo The password option shouldn't be mandatory.
 -spec listen([{port, inet:ip_port()} | {certfile, string()}
 	| {keyfile, string()} | {password, string()}
 	| {ip, inet:ip_address()}])
@@ -45,6 +77,13 @@ listen(Opts) ->
 		end,
 	ssl:listen(Port, ListenOpts).
 
+%% @doc Accept an incoming connection on a listen socket.
+%%
+%% Note that this function does both the transport accept and
+%% the SSL handshake.
+%%
+%% @see ssl:transport_accept/2
+%% @see ssl:ssl_accept/2
 -spec accept(ssl:sslsocket(), timeout())
 	-> {ok, ssl:sslsocket()} | {error, closed | timeout | atom()}.
 accept(LSocket, Timeout) ->
@@ -55,29 +94,41 @@ accept(LSocket, Timeout) ->
 			{error, Reason}
 	end.
 
+%% @doc Receive a packet from a socket in passive mode.
+%% @see ssl:recv/3
 -spec recv(ssl:sslsocket(), non_neg_integer(), timeout())
 	-> {ok, any()} | {error, closed | atom()}.
 recv(Socket, Length, Timeout) ->
 	ssl:recv(Socket, Length, Timeout).
 
+%% @doc Send a packet on a socket.
+%% @see ssl:send/2
 -spec send(ssl:sslsocket(), iolist()) -> ok | {error, atom()}.
 send(Socket, Packet) ->
 	ssl:send(Socket, Packet).
 
+%% @doc Set one or more options for a socket.
+%% @see ssl:setopts/2
 -spec setopts(ssl:sslsocket(), list()) -> ok | {error, atom()}.
 setopts(Socket, Opts) ->
 	ssl:setopts(Socket, Opts).
 
+%% @doc Assign a new controlling process <em>Pid</em> to <em>Socket</em>.
+%% @see ssl:controlling_process/2
 -spec controlling_process(ssl:sslsocket(), pid())
 	-> ok | {error, closed | not_owner | atom()}.
 controlling_process(Socket, Pid) ->
 	ssl:controlling_process(Socket, Pid).
 
+%% @doc Return the address and port for the other end of a connection.
+%% @see ssl:peername/1
 -spec peername(ssl:sslsocket())
 	-> {ok, {inet:ip_address(), inet:ip_port()}} | {error, atom()}.
 peername(Socket) ->
 	ssl:peername(Socket).
 
+%% @doc Close a TCP socket.
+%% @see ssl:close/1
 -spec close(ssl:sslsocket()) -> ok.
 close(Socket) ->
 	ssl:close(Socket).