Get rid of a ton of pointless comments

All of it can be found in the manual, which defines what the
code must do, and is always up to date unlike the code comments.

src/ranch.app.src

@@ -1,4 +1,4 @@
-%% Copyright (c) 2011-2012, Loïc Hoguin <essen@ninenines.eu>
+%% Copyright (c) 2011-2013, Loïc Hoguin <essen@ninenines.eu>
 %%
 %% Permission to use, copy, modify, and/or distribute this software for any
 %% purpose with or without fee is hereby granted, provided that the above

src/ranch.erl

@@ -1,4 +1,4 @@
-%% Copyright (c) 2011-2012, Loïc Hoguin <essen@ninenines.eu>
+%% Copyright (c) 2011-2013, Loïc Hoguin <essen@ninenines.eu>
 %%
 %% Permission to use, copy, modify, and/or distribute this software for any
 %% purpose with or without fee is hereby granted, provided that the above
@@ -12,7 +12,6 @@
 %% ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 %% OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 
-%% @doc Ranch API to start and stop listeners.
 -module(ranch).
 
 -export([start_listener/6]).
@@ -35,30 +34,6 @@
 -type ref() :: any().
 -export_type([ref/0]).
 
-%% @doc Start a listener for the given transport and protocol.
-%%
-%% A listener is effectively a pool of <em>NbAcceptors</em> acceptors.
-%% Acceptors accept connections on the given <em>Transport</em> and forward
-%% connections to the given <em>Protocol</em> handler. Both transport and
-%% protocol modules can be given options through the <em>TransOpts</em> and
-%% the <em>ProtoOpts</em> arguments. Available options are documented in the
-%% <em>listen</em> transport function and in the protocol module of your choice.
-%%
-%% All acceptor and connection processes are supervised by the listener.
-%%
-%% It is recommended to set a large enough number of acceptors to improve
-%% performance. The exact number depends of course on your hardware, on the
-%% protocol used and on the number of expected simultaneous connections.
-%%
-%% The <em>Transport</em> option <em>max_connections</em> allows you to define
-%% the maximum number of simultaneous connections for this listener. It defaults
-%% to 1024. See <em>ranch_listener</em> for more details on limiting the number
-%% of connections.
-%%
-%% <em>Ref</em> can be used to stop the listener later on.
-%%
-%% This function will return `{error, badarg}` if and only if the transport
-%% module given doesn't appear to be correct.
 -spec start_listener(ref(), non_neg_integer(), module(), any(), module(), any())
 	-> {ok, pid()} | {error, badarg}.
 start_listener(Ref, NbAcceptors, Transport, TransOpts, Protocol, ProtoOpts)
@@ -92,10 +67,6 @@ start_listener(Ref, NbAcceptors, Transport, TransOpts, Protocol, ProtoOpts)
 			Res
 	end.
 
-%% @doc Stop a listener identified by <em>Ref</em>.
-%%
-%% Note that stopping the listener will close all currently running
-%% connections abruptly.
 -spec stop_listener(ref()) -> ok | {error, not_found}.
 stop_listener(Ref) ->
 	case supervisor:terminate_child(ranch_sup, {ranch_listener_sup, Ref}) of
@@ -106,13 +77,6 @@ stop_listener(Ref) ->
 			{error, Reason}
 	end.
 
-%% @doc Return a child spec suitable for embedding.
-%%
-%% When you want to embed Ranch in another application, you can use this
-%% function to create a <em>ChildSpec</em> suitable for use in a supervisor.
-%% The parameters are the same as in <em>start_listener/6</em> but rather
-%% than hooking the listener to the Ranch internal supervisor, it just returns
-%% the spec.
 -spec child_spec(ref(), non_neg_integer(), module(), any(), module(), any())
 	-> supervisor:child_spec().
 child_spec(Ref, NbAcceptors, Transport, TransOpts, Protocol, ProtoOpts)
@@ -122,61 +86,38 @@ child_spec(Ref, NbAcceptors, Transport, TransOpts, Protocol, ProtoOpts)
 		Ref, NbAcceptors, Transport, TransOpts, Protocol, ProtoOpts
 	]}, permanent, infinity, supervisor, [ranch_listener_sup]}.
 
-%% @doc Acknowledge the accepted connection.
-%%
-%% Effectively used to make sure the socket control has been given to
-%% the protocol process before starting to use it.
 -spec accept_ack(ref()) -> ok.
 accept_ack(Ref) ->
 	receive {shoot, Ref, Transport, Socket, AckTimeout} ->
 		Transport:accept_ack(Socket, AckTimeout)
 	end.
 
-%% @doc Remove the calling process' connection from the pool.
-%%
-%% Useful if you have long-lived connections that aren't taking up
-%% resources and shouldn't be counted in the limited number of running
-%% connections.
 -spec remove_connection(ref()) -> ok.
 remove_connection(Ref) ->
 	ConnsSup = ranch_server:get_connections_sup(Ref),
 	ConnsSup ! {remove_connection, Ref},
 	ok.
 
-%% @doc Return the listener's port.
 -spec get_port(ref()) -> inet:port_number().
 get_port(Ref) ->
 	ranch_server:get_port(Ref).
 
-%% @doc Return the max number of connections allowed concurrently.
 -spec get_max_connections(ref()) -> max_conns().
 get_max_connections(Ref) ->
 	ranch_server:get_max_connections(Ref).
 
-%% @doc Set the max number of connections allowed concurrently.
 -spec set_max_connections(ref(), max_conns()) -> ok.
 set_max_connections(Ref, MaxConnections) ->
 	ranch_server:set_max_connections(Ref, MaxConnections).
 
-%% @doc Return the current protocol options for the given listener.
 -spec get_protocol_options(ref()) -> any().
 get_protocol_options(Ref) ->
 	ranch_server:get_protocol_options(Ref).
 
-%% @doc Upgrade the protocol options for the given listener.
-%%
-%% The upgrade takes place at the acceptor level, meaning that only the
-%% newly accepted connections receive the new protocol options. This has
-%% no effect on the currently opened connections.
 -spec set_protocol_options(ref(), any()) -> ok.
 set_protocol_options(Ref, Opts) ->
 	ranch_server:set_protocol_options(Ref, Opts).
 
-%% @doc Filter a list of options and remove all unwanted values.
-%%
-%% It takes a list of options, a list of allowed keys and an accumulator.
-%% This accumulator can be used to set default options that should never
-%% be overriden.
 -spec filter_options([{atom(), any()} | {raw, any(), any(), any()}],
 	[atom()], Acc) -> Acc when Acc :: [any()].
 filter_options([], _, Acc) ->
@@ -192,7 +133,6 @@ filter_options([Opt = {raw, _, _, _}|Tail], AllowedKeys, Acc) ->
 		false -> filter_options(Tail, AllowedKeys, Acc)
 	end.
 
-%% @doc Add an option to a list, but only if it wasn't previously set.
 -spec set_option_default(Opts, atom(), any())
 	-> Opts when Opts :: [{atom(), any()}].
 set_option_default(Opts, Key, Value) ->
@@ -201,7 +141,6 @@ set_option_default(Opts, Key, Value) ->
 		false -> [{Key, Value}|Opts]
 	end.
 
-%% @doc Start the given applications if they were not already started.
 -spec require([atom()]) -> ok.
 require([]) ->
 	ok;

src/ranch_acceptor.erl

@@ -1,4 +1,4 @@
-%% Copyright (c) 2011-2012, Loïc Hoguin <essen@ninenines.eu>
+%% Copyright (c) 2011-2013, Loïc Hoguin <essen@ninenines.eu>
 %%
 %% Permission to use, copy, modify, and/or distribute this software for any
 %% purpose with or without fee is hereby granted, provided that the above
@@ -12,25 +12,17 @@
 %% ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 %% OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 
-%% @private
 -module(ranch_acceptor).
 
-%% API.
 -export([start_link/3]).
-
-%% Internal.
 -export([loop/3]).
 
-%% API.
-
 -spec start_link(inet:socket(), module(), pid())
 	-> {ok, pid()}.
 start_link(LSocket, Transport, ConnsSup) ->
 	Pid = spawn_link(?MODULE, loop, [LSocket, Transport, ConnsSup]),
 	{ok, Pid}.
 
-%% Internal.
-
 -spec loop(inet:socket(), module(), pid()) -> no_return().
 loop(LSocket, Transport, ConnsSup) ->
 	_ = case Transport:accept(LSocket, infinity) of

src/ranch_acceptors_sup.erl

@@ -1,4 +1,4 @@
-%% Copyright (c) 2011-2012, Loïc Hoguin <essen@ninenines.eu>
+%% Copyright (c) 2011-2013, Loïc Hoguin <essen@ninenines.eu>
 %%
 %% Permission to use, copy, modify, and/or distribute this software for any
 %% purpose with or without fee is hereby granted, provided that the above
@@ -12,25 +12,17 @@
 %% ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 %% OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 
-%% @private
 -module(ranch_acceptors_sup).
 -behaviour(supervisor).
 
-%% API.
 -export([start_link/4]).
-
-%% supervisor.
 -export([init/1]).
 
-%% API.
-
 -spec start_link(ranch:ref(), non_neg_integer(), module(), any())
 	-> {ok, pid()}.
 start_link(Ref, NbAcceptors, Transport, TransOpts) ->
 	supervisor:start_link(?MODULE, [Ref, NbAcceptors, Transport, TransOpts]).
 
-%% supervisor.
-
 init([Ref, NbAcceptors, Transport, TransOpts]) ->
 	ConnsSup = ranch_server:get_connections_sup(Ref),
 	LSocket = case proplists:get_value(socket, TransOpts) of

src/ranch_app.erl

@@ -1,4 +1,4 @@
-%% Copyright (c) 2011-2012, Loïc Hoguin <essen@ninenines.eu>
+%% Copyright (c) 2011-2013, Loïc Hoguin <essen@ninenines.eu>
 %%
 %% Permission to use, copy, modify, and/or distribute this software for any
 %% purpose with or without fee is hereby granted, provided that the above
@@ -12,19 +12,15 @@
 %% ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 %% OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 
-%% @private
 -module(ranch_app).
 -behaviour(application).
 
-%% API.
 -export([start/2]).
 -export([stop/1]).
 -export([profile_output/0]).
 
-%% API.
-
 start(_, _) ->
-	consider_profiling(),
+	_ = consider_profiling(),
 	ranch_sup:start_link().
 
 stop(_) ->
@@ -38,9 +34,6 @@ profile_output() ->
 	eprof:log("total.profile"),
 	eprof:analyze(total).
 
-%% Internal.
-
--spec consider_profiling() -> profiling | not_profiling.
 consider_profiling() ->
 	case application:get_env(profile) of
 		{ok, true} ->

src/ranch_conns_sup.erl

@@ -1,4 +1,4 @@
-%% Copyright (c) 2011-2012, Loïc Hoguin <essen@ninenines.eu>
+%% Copyright (c) 2011-2013, Loïc Hoguin <essen@ninenines.eu>
 %%
 %% Permission to use, copy, modify, and/or distribute this software for any
 %% purpose with or without fee is hereby granted, provided that the above
@@ -12,8 +12,6 @@
 %% ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 %% OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 
-%% @private
-%%
 %% Make sure to never reload this module outside a release upgrade,
 %% as calling l(ranch_conns_sup) twice will kill the process and all
 %% the currently open connections.

src/ranch_listener_sup.erl

@@ -1,4 +1,4 @@
-%% Copyright (c) 2011-2012, Loïc Hoguin <essen@ninenines.eu>
+%% Copyright (c) 2011-2013, Loïc Hoguin <essen@ninenines.eu>
 %%
 %% Permission to use, copy, modify, and/or distribute this software for any
 %% purpose with or without fee is hereby granted, provided that the above
@@ -12,18 +12,12 @@
 %% ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 %% OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 
-%% @private
 -module(ranch_listener_sup).
 -behaviour(supervisor).
 
-%% API.
 -export([start_link/6]).
-
-%% supervisor.
 -export([init/1]).
 
-%% API.
-
 -spec start_link(ranch:ref(), non_neg_integer(), module(), any(), module(), any())
 	-> {ok, pid()}.
 start_link(Ref, NbAcceptors, Transport, TransOpts, Protocol, ProtoOpts) ->
@@ -33,8 +27,6 @@ start_link(Ref, NbAcceptors, Transport, TransOpts, Protocol, ProtoOpts) ->
 		Ref, NbAcceptors, Transport, TransOpts, Protocol
 	}).
 
-%% supervisor.
-
 init({Ref, NbAcceptors, Transport, TransOpts, Protocol}) ->
 	AckTimeout = proplists:get_value(ack_timeout, TransOpts, 5000),
 	ConnType = proplists:get_value(connection_type, TransOpts, worker),

src/ranch_protocol.erl

@@ -1,4 +1,4 @@
-%% Copyright (c) 2012, Loïc Hoguin <essen@ninenines.eu>
+%% Copyright (c) 2012-2013, Loïc Hoguin <essen@ninenines.eu>
 %%
 %% Permission to use, copy, modify, and/or distribute this software for any
 %% purpose with or without fee is hereby granted, provided that the above
@@ -12,7 +12,6 @@
 %% ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 %% OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 
-%% @private
 -module(ranch_protocol).
 
 %% Start a new connection process for the given socket.

src/ranch_server.erl

@@ -1,4 +1,4 @@
-%% Copyright (c) 2012, Loïc Hoguin <essen@ninenines.eu>
+%% Copyright (c) 2012-2013, Loïc Hoguin <essen@ninenines.eu>
 %%
 %% Permission to use, copy, modify, and/or distribute this software for any
 %% purpose with or without fee is hereby granted, provided that the above
@@ -12,7 +12,6 @@
 %% ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 %% OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 
-%% @private
 -module(ranch_server).
 -behaviour(gen_server).
 
@@ -47,17 +46,14 @@
 
 %% API.
 
-%% @doc Start the ranch_server gen_server.
 -spec start_link() -> {ok, pid()}.
 start_link() ->
 	gen_server:start_link({local, ?MODULE}, ?MODULE, [], []).
 
-%% @private
 -spec set_new_listener_opts(ranch:ref(), ranch:max_conns(), any()) -> ok.
 set_new_listener_opts(Ref, MaxConns, Opts) ->
 	gen_server:call(?MODULE, {set_new_listener_opts, Ref, MaxConns, Opts}).
 
-%% @doc Cleanup listener options after it has been stopped.
 -spec cleanup_listener_opts(ranch:ref()) -> ok.
 cleanup_listener_opts(Ref) ->
 	_ = ets:delete(?TAB, {port, Ref}),
@@ -65,61 +61,50 @@ cleanup_listener_opts(Ref) ->
 	_ = ets:delete(?TAB, {opts, Ref}),
 	ok.
 
-%% @doc Set a connection supervisor associated with specific listener.
 -spec set_connections_sup(ranch:ref(), pid()) -> ok.
 set_connections_sup(Ref, Pid) ->
 	true = gen_server:call(?MODULE, {set_connections_sup, Ref, Pid}),
 	ok.
 
-%% @doc Return the connection supervisor used by specific listener.
 -spec get_connections_sup(ranch:ref()) -> pid().
 get_connections_sup(Ref) ->
 	ets:lookup_element(?TAB, {conns_sup, Ref}, 2).
 
-%% @private
 -spec set_port(ranch:ref(), inet:port_number()) -> ok.
 set_port(Ref, Port) ->
 	gen_server:call(?MODULE, {set_port, Ref, Port}).
 
-%% @doc Return the listener's port.
 -spec get_port(ranch:ref()) -> inet:port_number().
 get_port(Ref) ->
 	ets:lookup_element(?TAB, {port, Ref}, 2).
 
-%% @doc Set the max number of connections allowed concurrently.
 -spec set_max_connections(ranch:ref(), ranch:max_conns()) -> ok.
 set_max_connections(Ref, MaxConnections) ->
 	gen_server:call(?MODULE, {set_max_conns, Ref, MaxConnections}).
 
-%% @doc Return the max number of connections allowed concurrently.
 -spec get_max_connections(ranch:ref()) -> ranch:max_conns().
 get_max_connections(Ref) ->
 	ets:lookup_element(?TAB, {max_conns, Ref}, 2).
 
-%% @doc Upgrade the protocol options.
 -spec set_protocol_options(ranch:ref(), any()) -> ok.
 set_protocol_options(Ref, ProtoOpts) ->
 	gen_server:call(?MODULE, {set_opts, Ref, ProtoOpts}).
 
-%% @doc Return the current protocol options.
 -spec get_protocol_options(ranch:ref()) -> any().
 get_protocol_options(Ref) ->
 	ets:lookup_element(?TAB, {opts, Ref}, 2).
 
-%% @doc Count the number of connections in the connection pool.
 -spec count_connections(ranch:ref()) -> non_neg_integer().
 count_connections(Ref) ->
 	ranch_conns_sup:active_connections(get_connections_sup(Ref)).
 
 %% gen_server.
 
-%% @private
 init([]) ->
 	Monitors = [{{erlang:monitor(process, Pid), Pid}, Ref} ||
 		[Ref, Pid] <- ets:match(?TAB, {{conns_sup, '$1'}, '$2'})],
 	{ok, #state{monitors=Monitors}}.
 
-%% @private
 handle_call({set_new_listener_opts, Ref, MaxConns, Opts}, _, State) ->
 	ets:insert(?TAB, {{max_conns, Ref}, MaxConns}),
 	ets:insert(?TAB, {{opts, Ref}, Opts}),
@@ -150,11 +135,9 @@ handle_call({set_opts, Ref, Opts}, _, State) ->
 handle_call(_Request, _From, State) ->
 	{reply, ignore, State}.
 
-%% @private
 handle_cast(_Request, State) ->
 	{noreply, State}.
 
-%% @private
 handle_info({'DOWN', MonitorRef, process, Pid, _},
 		State=#state{monitors=Monitors}) ->
 	{_, Ref} = lists:keyfind({MonitorRef, Pid}, 1, Monitors),
@@ -164,10 +147,8 @@ handle_info({'DOWN', MonitorRef, process, Pid, _},
 handle_info(_Info, State) ->
 	{noreply, State}.
 
-%% @private
 terminate(_Reason, _State) ->
 	ok.
 
-%% @private
 code_change(_OldVsn, State, _Extra) ->
 	{ok, State}.

src/ranch_ssl.erl

@@ -1,4 +1,4 @@
-%% Copyright (c) 2011-2012, Loïc Hoguin <essen@ninenines.eu>
+%% Copyright (c) 2011-2013, Loïc Hoguin <essen@ninenines.eu>
 %%
 %% Permission to use, copy, modify, and/or distribute this software for any
 %% purpose with or without fee is hereby granted, provided that the above
@@ -12,17 +12,6 @@
 %% 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 Ranch transport API.
-%%
-%% This transport requires the <em>crypto</em>, <em>asn1</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(ranch_ssl).
 -behaviour(ranch_transport).
 
@@ -71,77 +60,10 @@
 	| {verify_fun, {fun(), InitialUserState::term()}}].
 -export_type([opts/0]).
 
-%% @doc Name of this transport, <em>ssl</em>.
 name() -> ssl.
 
-%% @doc Atoms used to identify messages in {active, once | true} mode.
 messages() -> {ssl, ssl_closed, ssl_error}.
 
-%% @doc Listen for connections on the given port number.
-%%
-%% Calling this function returns a listening socket that can then
-%% The available options are:
-%%
-%% <dl>
-%%  <dt>backlog</dt><dd>Maximum length of the pending connections queue.
-%%   Defaults to 1024.</dd>
-%%  <dt>cacertfile</dt><dd>Optional. Path to file containing PEM encoded
-%%   CA certificates (trusted certificates used for verifying a peer
-%%   certificate).</dd>
-%%  <dt>cert</dt><dd>Optional. The DER encoded users certificate. If this
-%%   option is supplied it will override the certfile option.</dd>
-%%  <dt>certfile</dt><dd>Mandatory. Path to a file containing the user's
-%%   certificate.</dd>
-%%  <dt>ciphers</dt><dd>Optional. The cipher suites that should be supported.
-%%   The function ssl:cipher_suites/0 can be used to find all available
-%%   ciphers.</dd>
-%%  <dt>fail_if_no_peer_cert</dt><dd>Optional. Used together with {verify, verify_peer}.
-%%   If set to true, the server will fail if the client does not have a certificate
-%%   to send, i.e. sends a empty certificate, if set to false (that is by default)
-%%   it will only fail if the client sends an invalid certificate (an empty
-%%   certificate is considered valid).</dd>
-%%  <dt>hibernate_after</dt><dd>When an integer-value is specified, the ssl_connection
-%%   will go into hibernation after the specified number of milliseconds of inactivity,
-%%   thus reducing its memory footprint. When undefined is specified (this is the
-%%   default), the process will never go into hibernation.</dd>
-%%  <dt>ip</dt><dd>Interface to listen on. Listen on all interfaces
-%%   by default.</dd>
-%%  <dt>key</dt><dd>Optional. The DER encoded users private key. If this option
-%%   is supplied it will override the keyfile option.</dd>
-%%  <dt>keyfile</dt><dd>Optional. Path to the file containing the user's
-%%   private PEM encoded key.</dd>
-%%  <dt>next_protocols_advertised</dt><dd>Optional. Erlang R16B+ required.
-%%   List of protocols advertised by TLS Next Protocol Negotiation
-%%   extension.</dd>
-%%  <dt>nodelay</dt><dd>Optional. Enable TCP_NODELAY. Enabled by default.</dd>
-%%  <dt>password</dt><dd>Optional. String containing the user's password.
-%%   All private keyfiles must be password protected currently.</dd>
-%%  <dt>port</dt><dd>TCP port number to open. Defaults to 0 (see below)</dd>
-%%  <dt>reuse_session</dt><dd>Optional. Enables the ssl server to have a local
-%%   policy for deciding if a session should be reused or not, only meaningful
-%%   if reuse_sessions is set to true.</dd>
-%%  <dt>reuse_sessions</dt><dd>Optional. Specifies if the server should agree
-%%   to reuse sessions when the clients request to do so.</dd>
-%%  <dt>secure_renegotiate</dt><dd>Optional. Specifies if to reject renegotiation
-%%   attempt that does not live up to RFC 5746. By default secure_renegotiate is
-%%   set to false i.e. secure renegotiation will be used if possible but it will
-%%   fallback to unsecure renegotiation if the peer does not support RFC 5746.</dd>
-%%  <dt>verify</dt><dd>Optional. If set to verify_peer, performs an x509-path
-%%   validation and request the client for a certificate.</dd>
-%%  <dt>verify_fun</dt><dd>Optional. The verify fun will be called during the
-%%   X509-path validation when an error or an extension unknown to the ssl
-%%   application is encountered. Additionally it will be called when a certificate
-%%   is considered valid by the path validation to allow access to each certificate
-%%   in the path to the user application.</dd>
-%% </dl>
-%%
-%% You can listen to a random port by setting the port option to 0.
-%% It is then possible to retrieve this port number by calling
-%% sockname/1 on the listening socket. If you are using Ranch's
-%% listener API, then this port number can obtained through
-%% ranch:get_port/1 instead.
-%%
-%% @see ssl:listen/2
 -spec listen(opts()) -> {ok, ssl:sslsocket()} | {error, atom()}.
 listen(Opts) ->
 	ranch:require([crypto, asn1, public_key, ssl]),
@@ -163,13 +85,6 @@ listen(Opts) ->
 		[binary, {active, false}, {packet, raw},
 			{reuseaddr, true}, {nodelay, true}])).
 
-%% @doc Accept connections with the given listening socket.
-%%
-%% Note that this function does both the transport accept and
-%% the SSL handshake. The returned socket is thus fully connected.
-%%
-%% @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) ->
@@ -185,8 +100,6 @@ accept_ack(CSocket, Timeout) ->
 			error(Reason)
 	end.
 
-%% @private Experimental. Open a connection to the given host and port number.
-%% @see ssl:connect/3
 %% @todo Probably filter Opts?
 -spec connect(inet:ip_address() | inet:hostname(),
 	inet:port_number(), any())
@@ -195,8 +108,6 @@ connect(Host, Port, Opts) when is_integer(Port) ->
 	ssl:connect(Host, Port,
 		Opts ++ [binary, {active, false}, {packet, raw}]).
 
-%% @private Experimental. Open a connection to the given host and port number.
-%% @see ssl:connect/4
 %% @todo Probably filter Opts?
 -spec connect(inet:ip_address() | inet:hostname(),
 	inet:port_number(), any(), timeout())
@@ -206,80 +117,55 @@ connect(Host, Port, Opts, Timeout) when is_integer(Port) ->
 		Opts ++ [binary, {active, false}, {packet, raw}],
 		Timeout).
 
-%% @doc Receive data 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 data on a socket.
-%% @see ssl:send/2
 -spec send(ssl:sslsocket(), iodata()) -> ok | {error, atom()}.
 send(Socket, Packet) ->
 	ssl:send(Socket, Packet).
 
-%% @equiv sendfile(Socket, Filename, 0, 0, [])
 -spec sendfile(ssl:sslsocket(), file:name_all() | file:fd())
 	-> {ok, non_neg_integer()} | {error, atom()}.
 sendfile(Socket, Filename) ->
 	sendfile(Socket, Filename, 0, 0, []).
 
-%% @equiv sendfile(Socket, File, Offset, Bytes, [])
 -spec sendfile(ssl:sslsocket(), file:name_all() | file:fd(),
 		non_neg_integer(), non_neg_integer())
 	-> {ok, non_neg_integer()} | {error, atom()}.
 sendfile(Socket, File, Offset, Bytes) ->
 	sendfile(Socket, File, Offset, Bytes, []).
 
-%% @doc Send part of a file on a socket.
-%%
 %% Unlike with TCP, no syscall can be used here, so sending files
 %% through SSL will be much slower in comparison. Note that unlike
 %% file:sendfile/5 this function accepts either a file or a file name.
-%%
-%% @see ranch_transport:sendfile/6
-%% @see file:sendfile/5
 -spec sendfile(ssl:sslsocket(), file:name_all() | file:fd(),
 		non_neg_integer(), non_neg_integer(), ranch_transport:sendfile_opts())
 	-> {ok, non_neg_integer()} | {error, atom()}.
 sendfile(Socket, File, Offset, Bytes, Opts) ->
 	ranch_transport:sendfile(?MODULE, Socket, File, Offset, Bytes, Opts).
 
-%% @doc Set options on the given socket.
-%% @see ssl:setopts/2
 %% @todo Probably filter Opts?
 -spec setopts(ssl:sslsocket(), list()) -> ok | {error, atom()}.
 setopts(Socket, Opts) ->
 	ssl:setopts(Socket, Opts).
 
-%% @doc Give control of the socket to a new process.
-%%
-%% Must be called from the process currently controlling the socket,
-%% otherwise an {error, not_owner} tuple will be returned.
-%%
-%% @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 remote address and port of the connection.
-%% @see ssl:peername/1
 -spec peername(ssl:sslsocket())
 	-> {ok, {inet:ip_address(), inet:port_number()}} | {error, atom()}.
 peername(Socket) ->
 	ssl:peername(Socket).
 
-%% @doc Return the local address and port of the connection.
-%% @see ssl:sockname/1
 -spec sockname(ssl:sslsocket())
 	-> {ok, {inet:ip_address(), inet:port_number()}} | {error, atom()}.
 sockname(Socket) ->
 	ssl:sockname(Socket).
 
-%% @doc Close the given socket.
-%% @see ssl:close/1
 -spec close(ssl:sslsocket()) -> ok.
 close(Socket) ->
 	ssl:close(Socket).

src/ranch_sup.erl

@@ -1,4 +1,4 @@
-%% Copyright (c) 2011-2012, Loïc Hoguin <essen@ninenines.eu>
+%% Copyright (c) 2011-2013, Loïc Hoguin <essen@ninenines.eu>
 %%
 %% Permission to use, copy, modify, and/or distribute this software for any
 %% purpose with or without fee is hereby granted, provided that the above
@@ -12,25 +12,15 @@
 %% ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 %% OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 
-%% @private
 -module(ranch_sup).
 -behaviour(supervisor).
 
-%% API.
 -export([start_link/0]).
-
-%% supervisor.
 -export([init/1]).
 
--define(SUPERVISOR, ?MODULE).
-
-%% API.
-
 -spec start_link() -> {ok, pid()}.
 start_link() ->
-	supervisor:start_link({local, ?SUPERVISOR}, ?MODULE, []).
-
-%% supervisor.
+	supervisor:start_link({local, ?MODULE}, ?MODULE, []).
 
 init([]) ->
 	ranch_server = ets:new(ranch_server, [

src/ranch_tcp.erl

@@ -1,4 +1,4 @@
-%% Copyright (c) 2011-2012, Loïc Hoguin <essen@ninenines.eu>
+%% Copyright (c) 2011-2013, Loïc Hoguin <essen@ninenines.eu>
 %%
 %% Permission to use, copy, modify, and/or distribute this software for any
 %% purpose with or without fee is hereby granted, provided that the above
@@ -12,11 +12,6 @@
 %% 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 Ranch transport API.
-%%
-%% @see gen_tcp
 -module(ranch_tcp).
 -behaviour(ranch_transport).
 
@@ -49,34 +44,10 @@
 	| {send_timeout_close, boolean()}].
 -export_type([opts/0]).
 
-%% @doc Name of this transport, <em>tcp</em>.
 name() -> tcp.
 
-%% @doc Atoms used to identify messages in {active, once | true} mode.
 messages() -> {tcp, tcp_closed, tcp_error}.
 
-%% @doc Listen for connections on the given port number.
-%%
-%% Calling this function returns a listening socket that can then
-%% be passed to accept/2 to accept connections.
-%%
-%% The available options are:
-%% <dl>
-%%  <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>nodelay</dt><dd>Optional. Enable TCP_NODELAY. Enabled by default.</dd>
-%%  <dt>port</dt><dd>TCP port number to open. Defaults to 0 (see below).</dd>
-%% </dl>
-%%
-%% You can listen to a random port by setting the port option to 0.
-%% It is then possible to retrieve this port number by calling
-%% sockname/1 on the listening socket. If you are using Ranch's
-%% listener API, then this port number can obtained through
-%% ranch:get_port/1 instead.
-%%
-%% @see gen_tcp:listen/2
 -spec listen(opts()) -> {ok, inet:socket()} | {error, atom()}.
 listen(Opts) ->
 	Opts2 = ranch:set_option_default(Opts, backlog, 1024),
@@ -91,8 +62,6 @@ listen(Opts) ->
 		[binary, {active, false}, {packet, raw},
 			{reuseaddr, true}, {nodelay, true}])).
 
-%% @doc Accept connections with the given listening socket.
-%% @see gen_tcp:accept/2
 -spec accept(inet:socket(), timeout())
 	-> {ok, inet:socket()} | {error, closed | timeout | atom()}.
 accept(LSocket, Timeout) ->
@@ -102,8 +71,6 @@ accept(LSocket, Timeout) ->
 accept_ack(_, _) ->
 	ok.
 
-%% @private Experimental. Open a connection to the given host and port number.
-%% @see gen_tcp:connect/3
 %% @todo Probably filter Opts?
 -spec connect(inet:ip_address() | inet:hostname(),
 	inet:port_number(), any())
@@ -112,9 +79,6 @@ connect(Host, Port, Opts) when is_integer(Port) ->
 	gen_tcp:connect(Host, Port,
 		Opts ++ [binary, {active, false}, {packet, raw}]).
 
-%% @private Experimental. Open a connection to the given host and port
-%% number with a timeout.
-%% @see gen_tcp:connect/4
 %% @todo Probably filter Opts?
 -spec connect(inet:ip_address() | inet:hostname(),
 	inet:port_number(), any(), timeout())
@@ -124,39 +88,26 @@ connect(Host, Port, Opts, Timeout) when is_integer(Port) ->
 		Opts ++ [binary, {active, false}, {packet, raw}],
 		Timeout).
 
-%% @doc Receive data 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 data on a socket.
-%% @see gen_tcp:send/2
 -spec send(inet:socket(), iodata()) -> ok | {error, atom()}.
 send(Socket, Packet) ->
 	gen_tcp:send(Socket, Packet).
 
-%% @equiv sendfile(Socket, File, Offset, Bytes, [])
 -spec sendfile(inet:socket(), file:name_all() | file:fd())
 	-> {ok, non_neg_integer()} | {error, atom()}.
 sendfile(Socket, Filename) ->
 	sendfile(Socket, Filename, 0, 0, []).
 
-%% @equiv sendfile(Socket, File, Offset, Bytes, [])
 -spec sendfile(inet:socket(), file:name_all() | file:fd(), non_neg_integer(),
 		non_neg_integer())
 	-> {ok, non_neg_integer()} | {error, atom()}.
 sendfile(Socket, File, Offset, Bytes) ->
 	sendfile(Socket, File, Offset, Bytes, []).
 
-%% @doc Send part of a file on a socket.
-%%
-%% As with sendfile/2 this is the optimal way to send (parts) of files using
-%% TCP. Note that unlike file:sendfile/5 this function accepts either a raw file
-%% or a file name and the ordering of arguments is different.
-%%
-%% @see file:sendfile/5
 -spec sendfile(inet:socket(), file:name_all() | file:fd(), non_neg_integer(),
 		non_neg_integer(), [{chunk_size, non_neg_integer()}])
 	-> {ok, non_neg_integer()} | {error, atom()}.
@@ -182,46 +133,33 @@ sendfile(Socket, RawFile, Offset, Bytes, Opts) ->
 		Result -> Result
 	catch
 		error:{badmatch, {error, enotconn}} ->
-			%% file:sendfile/5 might fail by throwing a {badmatch, {error, enotconn}}
-			%% this is because its internal implementation fails with a badmatch in
+			%% file:sendfile/5 might fail by throwing a
+			%% {badmatch, {error, enotconn}}. This is because its
+			%% implementation fails with a badmatch in
 			%% prim_file:sendfile/10 if the socket is not connected.
 			{error, closed}
 	end.
 
-%% @doc Set options on the given socket.
-%% @see inet:setopts/2
 %% @todo Probably filter Opts?
 -spec setopts(inet:socket(), list()) -> ok | {error, atom()}.
 setopts(Socket, Opts) ->
 	inet:setopts(Socket, Opts).
 
-%% @doc Give control of the socket to a new process.
-%%
-%% Must be called from the process currently controlling the socket,
-%% otherwise an {error, not_owner} tuple will be returned.
-%%
-%% @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 remote address and port of the connection.
-%% @see inet:peername/1
 -spec peername(inet:socket())
 	-> {ok, {inet:ip_address(), inet:port_number()}} | {error, atom()}.
 peername(Socket) ->
 	inet:peername(Socket).
 
-%% @doc Return the local address and port of the connection.
-%% @see inet:sockname/1
 -spec sockname(inet:socket())
 	-> {ok, {inet:ip_address(), inet:port_number()}} | {error, atom()}.
 sockname(Socket) ->
 	inet:sockname(Socket).
 
-%% @doc Close the given socket.
-%% @see gen_tcp:close/1
 -spec close(inet:socket()) -> ok.
 close(Socket) ->
 	gen_tcp:close(Socket).

src/ranch_transport.erl

@@ -1,4 +1,4 @@
-%% Copyright (c) 2012, Loïc Hoguin <essen@ninenines.eu>
+%% Copyright (c) 2012-2013, Loïc Hoguin <essen@ninenines.eu>
 %%
 %% Permission to use, copy, modify, and/or distribute this software for any
 %% purpose with or without fee is hereby granted, provided that the above
@@ -12,7 +12,6 @@
 %% ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 %% OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 
-%% @private
 -module(ranch_transport).
 
 -export([sendfile/6]).
@@ -22,92 +21,39 @@
 -type sendfile_opts() :: [{chunk_size, non_neg_integer()}].
 -export_type([sendfile_opts/0]).
 
-%% Name of the transport.
 -callback name() -> atom().
-
 %% @todo -callback caps(secure | sendfile) -> boolean().
-
-%% Atoms used to identify messages in {active, once | true} mode.
 -callback messages() -> {OK::atom(), Closed::atom(), Error::atom()}.
-
-%% Listen for connections on the given port number.
-%%
-%% Calling this function returns a listening socket that can then
-%% be passed to accept/2 to accept connections.
-%%
-%% Available options may vary between transports.
-%%
-%% You can listen to a random port by setting the port option to 0.
-%% It is then possible to retrieve this port number by calling
-%% sockname/1 on the listening socket. If you are using Ranch's
-%% listener API, then this port number can obtained through
-%% ranch:get_port/1 instead.
 -callback listen(opts()) -> {ok, socket()} | {error, atom()}.
-
-%% Accept connections with the given listening socket.
 -callback accept(socket(), timeout())
 	-> {ok, socket()} | {error, closed | timeout | atom()}.
-
-%% Perform post-accept operations on the socket.
 -callback accept_ack(socket(), timeout()) -> ok.
-
-%% Experimental. Open a connection to the given host and port number.
 -callback connect(string(), inet:port_number(), opts())
 	-> {ok, socket()} | {error, atom()}.
-
-%% Experimental. Open a connection to the given host and port number
-%% with a timeout.
 -callback connect(string(), inet:port_number(), opts(), timeout())
 	-> {ok, socket()} | {error, atom()}.
-
-%% Receive data from a socket in passive mode.
 -callback recv(socket(), non_neg_integer(), timeout())
 	-> {ok, any()} | {error, closed | timeout | atom()}.
-
-%% Send data on a socket.
 -callback send(socket(), iodata()) -> ok | {error, atom()}.
-
-%% Send a file on a socket.
 -callback sendfile(socket(), file:name() | file:fd())
 	-> {ok, non_neg_integer()} | {error, atom()}.
-
-%% Send part of a file on a socket.
 -callback sendfile(socket(), file:name() | file:fd(), non_neg_integer(),
 		non_neg_integer()) -> {ok, non_neg_integer()} | {error, atom()}.
-
-%% Send part of a file on a socket.
 -callback sendfile(socket(), file:name() | file:fd(), non_neg_integer(),
 		non_neg_integer(), sendfile_opts())
 	-> {ok, non_neg_integer()} | {error, atom()}.
-
-%% Set options on the given socket.
 -callback setopts(socket(), opts()) -> ok | {error, atom()}.
-
-%% Give control of the socket to a new process.
-%%
-%% Must be called from the process currently controlling the socket,
-%% otherwise an {error, not_owner} tuple will be returned.
 -callback controlling_process(socket(), pid())
 	-> ok | {error, closed | not_owner | atom()}.
-
-%% Return the remote address and port of the connection.
 -callback peername(socket())
 	-> {ok, {inet:ip_address(), inet:port_number()}} | {error, atom()}.
-
-%% Return the local address and port of the connection.
 -callback sockname(socket())
 	-> {ok, {inet:ip_address(), inet:port_number()}} | {error, atom()}.
-
-%% Close the given socket.
 -callback close(socket()) -> ok.
 
-%% @doc Send part of a file on a socket.
-%%
 %% A fallback for transports that don't have a native sendfile implementation.
 %% Note that the ordering of arguments is different from file:sendfile/5 and
 %% that this function accepts either a raw file or a file name.
-%%
-%% @see file:sendfile/5
 -spec sendfile(module(), socket(), file:filename_all() | file:fd(),
 		non_neg_integer(), non_neg_integer(), sendfile_opts())
 	-> {ok, non_neg_integer()} | {error, atom()}.