Permalink
Browse files

Doc improvements

  • Loading branch information...
1 parent c432d56 commit b579637eb8b111862b12adaf9a3e5c94d4e7f8e3 Fernando Benavides committed Dec 29, 2010
Showing with 46 additions and 70 deletions.
  1. +4 −0 src/riak_err_app.erl
  2. +11 −28 src/riak_err_handler.erl
  3. +7 −38 src/riak_err_monitor.erl
  4. +16 −4 src/riak_err_stdlib.erl
  5. +3 −0 src/riak_err_sup.erl
  6. +5 −0 src/trunc_io.erl
@@ -101,14 +101,18 @@
start/2,
stop/1]).
+%% @doc Starts the application
+%% @spec start() -> 'ok' | {'error', term()}
-spec start() -> 'ok' | {'error', term()}.
start() ->
application:start(riak_err).
+%% @hidden
-spec start(normal | {takeover, node()} | {failover, node()}, term()) -> {ok, pid()}.
start(_StartType, _StartArgs) ->
riak_err_sup:start_link().
+%% @hidden
-spec stop([]) -> ok.
stop(_State) ->
ok.
@@ -77,27 +77,32 @@
%% @doc Add a supervised handler to the OTP kernel's
%% <tt>error_logger</tt> event server.
+%% @spec add_sup_handler() -> term()
-spec add_sup_handler() -> term().
add_sup_handler() ->
gen_event:add_sup_handler(error_logger, ?MODULE, []).
%% @doc Change the internal value of <tt>set_term_max_size</tt>.
+%% @spec set_term_max_size(pos_integer()) -> ok
-spec set_term_max_size(pos_integer()) -> ok.
set_term_max_size(Num) ->
gen_event:call(error_logger, ?MODULE, {set_term_max_size, Num}, infinity).
%% @doc Change the internal value of <tt>set_fmt_max_bytes</tt>.
+%% @spec set_fmt_max_bytes(pos_integer()) -> ok
-spec set_fmt_max_bytes(pos_integer()) -> ok.
set_fmt_max_bytes(Num) ->
gen_event:call(error_logger, ?MODULE, {set_fmt_max_bytes, Num}, infinity).
%% @doc Tell our error handler to reopen the <tt>sasl_error_logger</tt> file's
%% file handle (e.g., to assist log file rotation schemes).
+%% @spec reopen_log_file() -> ok
-spec reopen_log_file() -> ok.
reopen_log_file() ->
gen_event:call(error_logger, riak_err_handler, reopen_log_file, infinity).
%% @doc Debugging: get internal state record.
+%% @spec get_state() -> #state{}
-spec get_state() -> #state{}.
get_state() ->
gen_event:call(error_logger, ?MODULE, {get_state}, infinity).
@@ -106,11 +111,7 @@ get_state() ->
%%% Callback functions from gen_event
%%%----------------------------------------------------------------------
-%%----------------------------------------------------------------------
-%% Func: init/1
-%% Returns: {ok, State} |
-%% Other
-%%----------------------------------------------------------------------
+%% @hidden
-spec init([]) -> {ok, #state{}}.
init([]) ->
TermMaxSize = get_int_env(term_max_size, 10*1024),
@@ -136,12 +137,7 @@ init([]) ->
conslog_type = ConslogType,
conslog_sasl = ConslogSASL}}.
-%%----------------------------------------------------------------------
-%% Func: handle_event/2
-%% Returns: {ok, State} |
-%% {swap_handler, Args1, State1, Mod2, Args2} |
-%% remove_handler
-%%----------------------------------------------------------------------
+%% @hidden
-spec handle_event({atom(), pid(), {pid(), string() | atom(), any()}}, #state{}) -> {ok, #state{}}.
handle_event(Event, #state{errlog_type = ErrlogType, conslog_type = ConslogType,
log_fh = LogFH, term_max_size = TermMaxSize,
@@ -166,12 +162,7 @@ handle_event(Event, #state{errlog_type = ErrlogType, conslog_type = ConslogType,
end,
{ok, State}.
-%%----------------------------------------------------------------------
-%% Func: handle_call/2
-%% Returns: {ok, Reply, State} |
-%% {swap_handler, Reply, Args1, State1, Mod2, Args2} |
-%% {remove_handler, Reply}
-%%----------------------------------------------------------------------
+%% @hidden
-spec handle_call(term(), #state{}) -> {ok, ok, #state{}}.
handle_call(reopen_log_file, State) ->
case State#state.log_fh of
@@ -192,25 +183,17 @@ handle_call(_Request, State) ->
Reply = nosupported,
{ok, Reply, State}.
-%%----------------------------------------------------------------------
-%% Func: handle_info/2
-%% Returns: {ok, State} |
-%% {swap_handler, Args1, State1, Mod2, Args2} |
-%% remove_handler
-%%----------------------------------------------------------------------
+%% @hidden
-spec handle_info(term(), #state{}) -> {ok, #state{}}.
handle_info(_Info, State) ->
{ok, State}.
-%%----------------------------------------------------------------------
-%% Func: terminate/2
-%% Purpose: Shutdown the server
-%% Returns: any
-%%----------------------------------------------------------------------
+%% @hidden
-spec terminate(term(), #state{}) -> ok.
terminate(_Reason, _State) ->
ok.
+%% @hidden
-spec code_change(term(), #state{}, term()) -> {ok, #state{}}.
code_change(_OldVsn, State, _Extra) ->
{ok, State}.
@@ -50,13 +50,7 @@ stop() ->
%%% Callback functions from gen_server
%%%----------------------------------------------------------------------
-%%----------------------------------------------------------------------
-%% Func: init/1
-%% Returns: {ok, State} |
-%% {ok, State, Timeout} |
-%% ignore |
-%% {stop, Reason}
-%%----------------------------------------------------------------------
+%% @hidden
-spec init([]) -> {ok, #state{}}.
init([]) ->
%% Add our custom handler.
@@ -72,40 +66,22 @@ init([]) ->
{ok, TRef} = timer:send_interval(1000, reopen_log_file),
{ok, #state{tref = TRef}}.
-%%----------------------------------------------------------------------
-%% Func: handle_call/3
-%% Returns: {reply, Reply, State} |
-%% {reply, Reply, State, Timeout} |
-%% {noreply, State} |
-%% {noreply, State, Timeout} |
-%% {stop, Reason, Reply, State} | (terminate/2 is called)
-%% {stop, Reason, State} (terminate/2 is called)
-%%----------------------------------------------------------------------
+%% @hidden
-spec handle_call(stop | term(), reference(), #state{}) -> {stop, normal, ok, #state{}} | {reply, not_implemented, #state{}}.
handle_call(stop, _From, State) ->
{stop, normal, ok, State};
handle_call(_Request, _From, State) ->
{reply, not_implemented, State}.
-%%----------------------------------------------------------------------
-%% Func: handle_cast/2
-%% Returns: {noreply, State} |
-%% {noreply, State, Timeout} |
-%% {stop, Reason, State} (terminate/2 is called)
-%%----------------------------------------------------------------------
+%% @hidden
-spec handle_cast(tuple(), #state{}) -> {noreply, #state{}}.
handle_cast(Msg, State) ->
{Str, _} = trunc_io:print(Msg, State#state.max_len),
error_logger:error_msg("~w: ~s:handle_cast got ~s\n",
[self(), ?MODULE, Str]),
{noreply, State}.
-%%----------------------------------------------------------------------
-%% Func: handle_info/2
-%% Returns: {noreply, State} |
-%% {noreply, State, Timeout} |
-%% {stop, Reason, State} (terminate/2 is called)
-%%----------------------------------------------------------------------
+%% @hidden
-spec handle_info(reopen_log_file | {gen_event_EXIT, ?MODULE, term()} | tuple(), #state{}) -> {noreply, #state{}} | {stop, gen_event_EXIT, #state{}}.
handle_info(reopen_log_file, State) ->
ok = riak_err_handler:reopen_log_file(),
@@ -128,19 +104,12 @@ handle_info(Info, State) ->
[self(), ?MODULE, Str]),
{noreply, State}.
-%%----------------------------------------------------------------------
-%% Func: terminate/2
-%% Purpose: Shutdown the server
-%% Returns: any (ignored by gen_server)
-%%----------------------------------------------------------------------
+%% @hidden
-spec terminate(term(), #state{}) -> ok.
terminate(_Reason, _State) ->
ok.
+%% @hidden
-spec code_change(term(), #state{}, term()) -> {ok, #state{}}.
code_change(_OldVsn, State, _Extra) ->
- {ok, State}.
-
-%%%----------------------------------------------------------------------
-%%% Internal functions
-%%%----------------------------------------------------------------------
+ {ok, State}.
@@ -22,7 +22,7 @@
%%
%% All functions in this module are covered by the Erlang/OTP source
%% distribution's license, the Erlang Public License. See
-%% http://www.erlang.org/ for full details.
+%% {@link http://www.erlang.org/} for full details.
-module(riak_err_stdlib).
-export([write_time/2, maybe_utc/1]).
@@ -40,8 +40,9 @@
-type t_time() :: {hour(),minute(),second()}.
-type t_datetime1970() :: {{year1970(),month(),day()},t_time()}.
-%% From OTP stdlib's error_logger_tty_h.erl ... These functions aren't
+%% @doc From OTP stdlib's error_logger_tty_h.erl ... These functions aren't
%% exported.
+%% @spec write_time({utc, t_datetime1970()} | t_datetime1970(), string()) -> string()
-spec write_time({utc, t_datetime1970()} | t_datetime1970(), string()) -> string().
write_time({utc,{{Y,Mo,D},{H,Mi,S}}},Type) ->
io_lib:format("~n=~s==== ~p-~s-~p::~s:~s:~s UTC ===~n",
@@ -50,6 +51,9 @@ write_time({{Y,Mo,D},{H,Mi,S}},Type) ->
io_lib:format("~n=~s==== ~p-~s-~p::~s:~s:~s ===~n",
[Type,D,month(Mo),Y,t(H),t(Mi),t(S)]).
+%% @doc From OTP stdlib's error_logger_tty_h.erl ... These functions aren't
+%% exported.
+%% @spec maybe_utc(t_datetime1970()) -> {utc, t_datetime1970()} | t_datetime1970()
-spec maybe_utc(t_datetime1970()) -> {utc, t_datetime1970()} | t_datetime1970().
maybe_utc(Time) ->
UTC = case application:get_env(sasl, utc_log) of
@@ -95,17 +99,24 @@ month(10) -> "Oct";
month(11) -> "Nov";
month(12) -> "Dec".
-%% From OTP sasl's sasl_report.erl ... These functions aren't
+%% @doc From OTP sasl's sasl_report.erl ... These functions aren't
%% exported.
+%% @spec is_my_error_report(atom()) -> boolean()
-spec is_my_error_report(atom()) -> boolean().
is_my_error_report(supervisor_report) -> true;
is_my_error_report(crash_report) -> true;
is_my_error_report(_) -> false.
+%% @doc From OTP sasl's sasl_report.erl ... These functions aren't
+%% exported.
+%% @spec is_my_info_report(atom()) -> boolean()
-spec is_my_info_report(atom()) -> boolean().
is_my_info_report(progress) -> true;
is_my_info_report(_) -> false.
+%% @doc From OTP sasl's sasl_report.erl ... These functions aren't
+%% exported.
+%% @spec sup_get(term(), [proplists:property()]) -> term()
-spec sup_get(term(), [proplists:property()]) -> term().
sup_get(Tag, Report) ->
case lists:keysearch(Tag, 1, Report) of
@@ -115,7 +126,8 @@ sup_get(Tag, Report) ->
""
end.
-%% From OTP stdlib's proc_lib.erl ... These functions aren't exported.
+%% @doc From OTP stdlib's proc_lib.erl ... These functions aren't exported.
+%% @spec proc_lib_format([term()], pos_integer()) -> string()
-spec proc_lib_format([term()], pos_integer()) -> string().
proc_lib_format([OwnReport,LinkReport], FmtMaxBytes) ->
OwnFormat = format_report(OwnReport, FmtMaxBytes),
@@ -30,12 +30,15 @@
-type startlink_err() :: {'already_started', pid()} | 'shutdown' | term().
-type startlink_ret() :: {'ok', pid()} | 'ignore' | {'error', startlink_err()}.
+%% @doc Starts the supervisor
+%% @spec start_link() -> startlink_ret()
-spec start_link() -> startlink_ret().
start_link() ->
supervisor:start_link({local, ?SERVER}, ?MODULE, []).
% R14B spec is commented, use R13B spec for now.
%-spec init([]) -> {ok, {{one_for_one, 1000, 3600}, [supervisor:child_spec()]}}.
+%% @hidden
-spec init([]) -> {ok, {{one_for_one, 1000, 3600}, [tuple()]}}.
init([]) ->
RestartStrategy = one_for_one,
View
@@ -169,10 +169,12 @@ alist(L, Max) ->
%%--------------------
%% The start of a test suite. So far, it only checks for not crashing.
+%% @hidden
-spec test() -> ok.
test() ->
test(trunc_io, print).
+%% @hidden
-spec test(atom(), atom()) -> ok.
test(Mod, Func) ->
Simple_items = [atom, 1234, 1234.0, {tuple}, [], [list], "string", self(),
@@ -202,19 +204,22 @@ test(Mod, Func) ->
lists:foreach(G, Tuples),
lists:foreach(G, Lists).
+%% @hidden
-spec perf() -> ok.
perf() ->
{New, _} = timer:tc(trunc_io, perf, [trunc_io, print, 1000]),
{Old, _} = timer:tc(trunc_io, perf, [io_lib, write, 1000]),
io:fwrite("New code took ~p us, old code ~p\n", [New, Old]).
+%% @hidden
-spec perf(atom(), atom(), integer()) -> done.
perf(M, F, Reps) when Reps > 0 ->
test(M,F),
perf(M,F,Reps-1);
perf(_,_,_) ->
done.
+%% @hidden
%% Performance test. Needs a particularly large term I saved as a binary...
-spec perf1() -> {non_neg_integer(), non_neg_integer()}.
perf1() ->

0 comments on commit b579637

Please sign in to comment.