Remove outdated comments, all edoc, plus a few minor tweaks

manual/cowboy_req.md

@@ -614,7 +614,8 @@ Response related exports
 >
 > If a `Length` is provided, it will be sent in the
 > content-length header in the response. It is recommended
-> to set the length if it can be known in advance.
+> to set the length if it can be known in advance. Otherwise,
+> the transfer-encoding header will be set to identity.
 >
 > This function will only be called if the response is sent
 > using the `reply/2` or `reply/3` function.

src/cowboy.erl

@@ -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 Convenience API to start and stop HTTP/HTTPS listeners.
 -module(cowboy).
 
 -export([start_http/4]).
@@ -37,23 +36,20 @@
 	fun((http_status(), http_headers(), iodata(), Req) -> Req).
 -export_type([onresponse_fun/0]).
 
-%% @doc Start an HTTP listener.
 -spec start_http(ranch:ref(), non_neg_integer(), ranch_tcp:opts(),
 	cowboy_protocol:opts()) -> {ok, pid()} | {error, any()}.
 start_http(Ref, NbAcceptors, TransOpts, ProtoOpts)
 		when is_integer(NbAcceptors), NbAcceptors > 0 ->
 	ranch:start_listener(Ref, NbAcceptors,
 		ranch_tcp, TransOpts, cowboy_protocol, ProtoOpts).
 
-%% @doc Start an HTTPS listener.
 -spec start_https(ranch:ref(), non_neg_integer(), ranch_ssl:opts(),
 	cowboy_protocol:opts()) -> {ok, pid()} | {error, any()}.
 start_https(Ref, NbAcceptors, TransOpts, ProtoOpts)
 		when is_integer(NbAcceptors), NbAcceptors > 0 ->
 	ranch:start_listener(Ref, NbAcceptors,
 		ranch_ssl, TransOpts, cowboy_protocol, ProtoOpts).
 
-%% @doc Start a SPDY listener.
 -spec start_spdy(ranch:ref(), non_neg_integer(), ranch_ssl:opts(),
 	cowboy_spdy:opts()) -> {ok, pid()} | {error, any()}.
 start_spdy(Ref, NbAcceptors, TransOpts, ProtoOpts)
@@ -66,20 +62,14 @@ start_spdy(Ref, NbAcceptors, TransOpts, ProtoOpts)
 	ranch:start_listener(Ref, NbAcceptors,
 		ranch_ssl, TransOpts2, cowboy_spdy, ProtoOpts).
 
-%% @doc Stop a listener.
 -spec stop_listener(ranch:ref()) -> ok | {error, not_found}.
 stop_listener(Ref) ->
 	ranch:stop_listener(Ref).
 
-%% @doc Convenience function for setting an environment value.
-%%
-%% Allows you to update live an environment value used by middlewares.
-%% This function is primarily intended to simplify updating the dispatch
-%% list used for routing.
 -spec set_env(ranch:ref(), atom(), any()) -> ok.
 set_env(Ref, Name, Value) ->
 	Opts = ranch:get_protocol_options(Ref),
 	{_, Env} = lists:keyfind(env, 1, Opts),
-	Env2 = [{Name, Value}|lists:keydelete(Name, 1, Env)],
-	Opts2 = lists:keyreplace(env, 1, Opts, {env, Env2}),
+	Opts2 = lists:keyreplace(env, 1, Opts,
+		{env, lists:keystore(Name, 1, Env, {Name, Value})}),
 	ok = ranch:set_protocol_options(Ref, Opts2).

src/cowboy_app.erl

@@ -12,16 +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(cowboy_app).
 -behaviour(application).
 
-%% API.
 -export([start/2]).
 -export([stop/1]).
 
-%% API.
-
 start(_Type, _Args) ->
 	cowboy_sup:start_link().
 

src/cowboy_bstr.erl

@@ -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 Binary string manipulation.
 -module(cowboy_bstr).
 
 %% Binary strings.
@@ -24,11 +23,9 @@
 -export([char_to_lower/1]).
 -export([char_to_upper/1]).
 
-%% @doc Capitalize a token.
-%%
 %% The first letter and all letters after a dash are capitalized.
 %% This is the form seen for header names in the HTTP/1.1 RFC and
-%% others. Note that using this form isn't required, as header name
+%% others. Note that using this form isn't required, as header names
 %% are case insensitive, and it is only provided for use with eventual
 %% badly implemented clients.
 -spec capitalize_token(B) -> B when B::binary().
@@ -43,19 +40,14 @@ capitalize_token(<< C, Rest/bits >>, true, Acc) ->
 capitalize_token(<< C, Rest/bits >>, false, Acc) ->
 	capitalize_token(Rest, false, << Acc/binary, (char_to_lower(C)) >>).
 
-%% @doc Convert a binary string to lowercase.
 -spec to_lower(B) -> B when B::binary().
 to_lower(B) ->
 	<< << (char_to_lower(C)) >> || << C >> <= B >>.
 
-%% @doc Convert a binary string to uppercase.
 -spec to_upper(B) -> B when B::binary().
 to_upper(B) ->
 	<< << (char_to_upper(C)) >> || << C >> <= B >>.
 
-%% @doc Convert [A-Z] characters to lowercase.
-%% @end
-%% We gain noticeable speed by matching each value directly.
 -spec char_to_lower(char()) -> char().
 char_to_lower($A) -> $a;
 char_to_lower($B) -> $b;
@@ -85,7 +77,6 @@ char_to_lower($Y) -> $y;
 char_to_lower($Z) -> $z;
 char_to_lower(Ch) -> Ch.
 
-%% @doc Convert [a-z] characters to uppercase.
 -spec char_to_upper(char()) -> char().
 char_to_upper($a) -> $A;
 char_to_upper($b) -> $B;
@@ -118,9 +109,7 @@ char_to_upper(Ch) -> Ch.
 %% Tests.
 
 -ifdef(TEST).
-
 capitalize_token_test_() ->
-	%% {Header, Result}
 	Tests = [
 		{<<"heLLo-woRld">>, <<"Hello-World">>},
 		{<<"Sec-Websocket-Version">>, <<"Sec-Websocket-Version">>},
@@ -131,5 +120,4 @@ capitalize_token_test_() ->
 		{<<"Sec-WebSocket---Version">>, <<"Sec-Websocket---Version">>}
 	],
 	[{H, fun() -> R = capitalize_token(H) end} || {H, R} <- Tests].
-
 -endif.

src/cowboy_clock.erl

@@ -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.
 
-%% @doc Date and time related functions.
-%%
 %% While a gen_server process runs in the background to update
 %% the cache of formatted dates every second, all API calls are
 %% local and directly read from the ETS cache table, providing
@@ -41,68 +39,55 @@
 	tref = undefined :: undefined | timer:tref()
 }).
 
--define(SERVER, ?MODULE).
--define(TABLE, ?MODULE).
-
 %% API.
 
-%% @private
 -spec start_link() -> {ok, pid()}.
 start_link() ->
-	gen_server:start_link({local, ?SERVER}, ?MODULE, [], []).
+	gen_server:start_link({local, ?MODULE}, ?MODULE, [], []).
 
-%% @private
 -spec stop() -> stopped.
 stop() ->
-	gen_server:call(?SERVER, stop).
+	gen_server:call(?MODULE, stop).
 
-%% @doc Return the current date and time formatted according to RFC-1123.
 -spec rfc1123() -> binary().
 rfc1123() ->
-	ets:lookup_element(?TABLE, rfc1123, 2).
+	ets:lookup_element(?MODULE, rfc1123, 2).
 
-%% @doc Return the given date and time formatted according to RFC-1123.
 -spec rfc1123(calendar:datetime()) -> binary().
 rfc1123(DateTime) ->
 	update_rfc1123(<<>>, undefined, DateTime).
 
 %% gen_server.
 
-%% @private
 init([]) ->
-	?TABLE = ets:new(?TABLE, [set, protected,
+	?MODULE = ets:new(?MODULE, [set, protected,
 		named_table, {read_concurrency, true}]),
 	T = erlang:universaltime(),
 	B = update_rfc1123(<<>>, undefined, T),
 	{ok, TRef} = timer:send_interval(1000, update),
-	ets:insert(?TABLE, {rfc1123, B}),
+	ets:insert(?MODULE, {rfc1123, B}),
 	{ok, #state{universaltime=T, rfc1123=B, tref=TRef}}.
 
-%% @private
 handle_call(stop, _From, State=#state{tref=TRef}) ->
 	{ok, cancel} = timer:cancel(TRef),
 	{stop, normal, stopped, State};
 handle_call(_Request, _From, State) ->
 	{reply, ignored, State}.
 
-%% @private
 handle_cast(_Msg, State) ->
 	{noreply, State}.
 
-%% @private
 handle_info(update, #state{universaltime=Prev, rfc1123=B1, tref=TRef}) ->
 	T = erlang:universaltime(),
 	B2 = update_rfc1123(B1, Prev, T),
-	ets:insert(?TABLE, {rfc1123, B2}),
+	ets:insert(?MODULE, {rfc1123, B2}),
 	{noreply, #state{universaltime=T, rfc1123=B2, tref=TRef}};
 handle_info(_Info, State) ->
 	{noreply, State}.
 
-%% @private
 terminate(_Reason, _State) ->
 	ok.
 
-%% @private
 code_change(_OldVsn, State, _Extra) ->
 	{ok, State}.
 
@@ -174,7 +159,6 @@ month(12) -> <<"Dec">>.
 %% Tests.
 
 -ifdef(TEST).
-
 update_rfc1123_test_() ->
 	Tests = [
 		{<<"Sat, 14 May 2011 14:25:33 GMT">>, undefined,
@@ -215,5 +199,4 @@ pad_int_test_() ->
 		{56, <<"56">>}, {57, <<"57">>}, {58, <<"58">>}, {59, <<"59">>}
 	],
 	[{I, fun() -> O = pad_int(I) end} || {I, O} <- Tests].
-
 -endif.

src/cowboy_handler.erl

@@ -12,7 +12,7 @@
 %% ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 %% OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 
-%% @doc Handler middleware.
+%% Handler middleware.
 %%
 %% Execute the handler given by the <em>handler</em> and <em>handler_opts</em>
 %% environment values. The result of this execution is added to the
@@ -27,8 +27,6 @@
 %% by default. This can be configured through the <em>loop_max_buffer</em>
 %% environment value. The request will be terminated with an
 %% <em>{error, overflow}</em> reason if this threshold is reached.
-%%
-%% @see cowboy_http_handler
 -module(cowboy_handler).
 -behaviour(cowboy_middleware).
 
@@ -45,7 +43,6 @@
 	resp_sent = false :: boolean()
 }).
 
-%% @private
 -spec execute(Req, Env)
 	-> {ok, Req, Env} | {error, 500, Req}
 	| {suspend, ?MODULE, handler_loop, [any()]}
@@ -148,8 +145,6 @@ handler_after_callback(Req, State=#state{resp_sent=false}, Handler,
 handler_after_callback(Req, State, Handler, HandlerState) ->
 	handler_before_loop(Req, State, Handler, HandlerState).
 
-%% We don't listen for Transport closes because that would force us
-%% to receive data and buffer it indefinitely.
 -spec handler_before_loop(Req, #state{}, module(), any())
 	-> {ok, Req, cowboy_middleware:env()}
 	| {error, 500, Req} | {suspend, module(), atom(), [any()]}
@@ -177,7 +172,6 @@ handler_loop_timeout(State=#state{loop_timeout=Timeout,
 	TRef = erlang:start_timer(Timeout, self(), ?MODULE),
 	State#state{loop_timeout_ref=TRef}.
 
-%% @private
 -spec handler_loop(Req, #state{}, module(), any())
 	-> {ok, Req, cowboy_middleware:env()}
 	| {error, 500, Req} | {suspend, module(), atom(), [any()]}