Documentation!

src/error_logger_lager_h.erl

@@ -14,6 +14,13 @@
 %% specific language governing permissions and limitations
 %% under the License.
 
+%% @doc A error_logger backend for redirecting events into lager.
+%% Error messages and crash logs are also optionally written to a crash log.
+
+%% @see lager_crash_log
+
+%% @private
+
 -module(error_logger_lager_h).
 
 -behaviour(gen_event).

src/lager.erl

@@ -14,6 +14,8 @@
 %% specific language governing permissions and limitations
 %% under the License.
 
+%% @doc The lager logging framework.
+
 -module(lager).
 
 %% API
@@ -24,6 +26,8 @@
 
 %% API
 
+%% @doc Start the application. Mainly useful for using `-s lager' as a command
+%% line switch to the VM to make lager start on boot.
 start() -> start(lager).
 
 start(App) ->
@@ -37,6 +41,7 @@ start_ok(App, {error, {not_started, Dep}}) ->
 start_ok(App, {error, Reason}) -> 
     erlang:error({app_start_failed, App, Reason}).
 
+%% @private
 log(Level, Module, Function, Line, Pid, Time, Message) ->
     Timestamp = lager_util:format_time(Time),
     Msg = [io_lib:format("[~p] ~p@~p:~p:~p ", [Level, Pid, Module,
@@ -44,6 +49,7 @@ log(Level, Module, Function, Line, Pid, Time, Message) ->
     gen_event:sync_notify(lager_event, {log, lager_util:level_to_num(Level),
             Timestamp, Msg}).
 
+%% @private
 log(Level, Module, Function, Line, Pid, Time, Format, Args) ->
     Timestamp = lager_util:format_time(Time),
     Msg = [io_lib:format("[~p] ~p@~p:~p:~p ", [Level, Pid, Module,
@@ -51,18 +57,21 @@ log(Level, Module, Function, Line, Pid, Time, Format, Args) ->
     gen_event:sync_notify(lager_event, {log, lager_util:level_to_num(Level),
             Timestamp, Msg}).
 
+%% @doc Manually log a message into lager without using the parse transform.
 log(Level, Pid, Message) ->
     Timestamp = lager_util:format_time(),
     Msg = [io_lib:format("[~p] ~p ", [Level, Pid]), Message],
     gen_event:sync_notify(lager_event, {log, lager_util:level_to_num(Level),
             Timestamp, Msg}).
 
+%% @doc Manually log a message into lager without using the parse transform.
 log(Level, Pid, Format, Args) ->
     Timestamp = lager_util:format_time(),
     Msg = [io_lib:format("[~p] ~p ", [Level, Pid]), io_lib:format(Format, Args)],
     gen_event:sync_notify(lager_event, {log, lager_util:level_to_num(Level),
             Timestamp, Msg}).
 
+%% @doc Set the loglevel for a particular backend.
 set_loglevel(Handler, Level) when is_atom(Level) ->
     Reply = gen_event:call(lager_event, Handler, {set_loglevel, Level}),
     %% recalculate min log level
@@ -70,6 +79,8 @@ set_loglevel(Handler, Level) when is_atom(Level) ->
     lager_mochiglobal:put(loglevel, MinLog),
     Reply.
 
+%% @doc Set the loglevel for a particular backend that has multiple identifiers
+%% (eg. the file backend).
 set_loglevel(Handler, Ident, Level) when is_atom(Level) ->
     Reply = gen_event:call(lager_event, Handler, {set_loglevel, Ident, Level}),
     %% recalculate min log level
@@ -77,6 +88,8 @@ set_loglevel(Handler, Ident, Level) when is_atom(Level) ->
     lager_mochiglobal:put(loglevel, MinLog),
     Reply.
 
+%% @doc Get the loglevel for a particular backend. In the case that the backend
+%% has multiple identifiers, the lowest is returned
 get_loglevel(Handler) ->
     case gen_event:call(lager_event, Handler, get_loglevel) of
         X when is_integer(X) ->
@@ -84,10 +97,12 @@ get_loglevel(Handler) ->
         Y -> Y
     end.
 
+%% @private
 get_loglevels() ->
     [gen_event:call(lager_event, Handler, get_loglevel) ||
         Handler <- gen_event:which_handlers(lager_event)].
 
+%% @private
 minimum_loglevel([]) ->
     9; %% higher than any log level, logging off
 minimum_loglevel(Levels) ->

src/lager_app.erl

@@ -14,6 +14,10 @@
 %% specific language governing permissions and limitations
 %% under the License.
 
+%% @doc Lager's application module. Not a lot to see here.
+
+%% @private
+
 -module(lager_app).
 
 -behaviour(application).

src/lager_console_backend.erl

@@ -14,6 +14,9 @@
 %% specific language governing permissions and limitations
 %% under the License.
 
+%% @doc Console backend for lager. Configured with a single option, the loglevel
+%% desired.
+
 -module(lager_console_backend).
 
 -behaviour(gen_event).
@@ -23,9 +26,11 @@
 
 -record(state, {level}).
 
+%% @private
 init(Level) ->
     {ok, #state{level=lager_util:level_to_num(Level)}}.
 
+%% @private
 handle_call(get_loglevel, #state{level=Level} = State) ->
     {ok, Level, State};
 handle_call({set_loglevel, Level}, State) ->
@@ -33,17 +38,21 @@ handle_call({set_loglevel, Level}, State) ->
 handle_call(_Request, State) ->
     {ok, ok, State}.
 
+%% @private
 handle_event({log, Level, Time, Message}, #state{level=LogLevel} = State) when Level >= LogLevel ->
     io:put_chars([Time, " ", Message, "\n"]),
     {ok, State};
 handle_event(_Event, State) ->
     {ok, State}.
 
+%% @private
 handle_info(_Info, State) ->
     {ok, State}.
 
+%% @private
 terminate(_Reason, _State) ->
     ok.
 
+%% @private
 code_change(_OldVsn, State, _Extra) ->
     {ok, State}.

src/lager_crash_log.erl

@@ -14,6 +14,12 @@
 %% specific language governing permissions and limitations
 %% under the License.
 
+%% @doc Lager crash log writer. This module implements a gen_server which writes
+%% error_logger error messages out to a file in their original format. The
+%% location to which it logs is configured by the environment var `crash_log'.
+%% Omitting this variable disables crash logging. Crash logs are printed safely
+%% using trunc_io via code mostly lifted from riak_err.
+
 -module(lager_crash_log).
 
 -behaviour(gen_server).
@@ -39,12 +45,15 @@
         _ -> ok
     end).
 
+%% @private
 start_link(Filename) ->
     gen_server:start_link({local, ?MODULE}, ?MODULE, [Filename], []).
 
+%% @private
 start(Filename) ->
     gen_server:start({local, ?MODULE}, ?MODULE, [Filename], []).
 
+%% @private
 init([Filename]) ->
     case lager_util:open_logfile(Filename, false) of
         {ok, {FD, Inode}} ->
@@ -53,9 +62,11 @@ init([Filename]) ->
             Error
     end.
 
+%% @private
 handle_call(_Call, _From, State) ->
     {reply, ok, State}.
 
+%% @private
 handle_cast({log, Event}, #state{name=Name, fd=FD, inode=Inode, flap=Flap} = State) ->
     FmtMaxBytes = 1024,
     TermMaxSize = 500,
@@ -101,12 +112,15 @@ handle_cast({log, Event}, #state{name=Name, fd=FD, inode=Inode, flap=Flap} = Sta
 handle_cast(_Request, State) ->
     {noreply, State}.
 
+%% @private
 handle_info(_Info, State) ->
     {noreply, State}.
 
+%% @private
 terminate(_Reason, _State) ->
     ok.
 
+%% @private
 code_change(_OldVsn, State, _Extra) ->
     {ok, State}.
 

src/lager_file_backend.erl

@@ -14,6 +14,12 @@
 %% specific language governing permissions and limitations
 %% under the License.
 
+%% @doc File backend for lager, with multiple file support.
+%% Multiple files are supported, each with the path and the loglevel being
+%% configurable. The configuration paramter for this backend is a list of
+%% 2-tuples of the form `{FileName, Level}'. This backend supports external log
+%% rotation and will re-open handles to files if the inode changes.
+
 -module(lager_file_backend).
 
 -behaviour(gen_event).
@@ -47,7 +53,7 @@
         _ -> ok
     end).
 
-
+%% @private
 init(LogFiles) ->
     Files = [begin
                 case lager_util:open_logfile(Name, true) of
@@ -62,6 +68,7 @@ init(LogFiles) ->
         {Name, Level} <- LogFiles],
     {ok, #state{files=Files}}.
 
+%% @private
 handle_call({set_loglevel, _}, State) ->
     {ok, {error, missing_identifier}, State};
 handle_call({set_loglevel, Ident, Level}, #state{files=Files} = State) ->
@@ -86,6 +93,7 @@ handle_call(get_loglevel, #state{files=Files} = State) ->
 handle_call(_Request, State) ->
     {ok, ok, State}.
 
+%% @private
 handle_event({log, Level, Time, Message}, #state{files=Files} = State) ->
     NewFiles = lists:map(
         fun(#file{level=L} = File) when Level >= L ->
@@ -97,9 +105,11 @@ handle_event({log, Level, Time, Message}, #state{files=Files} = State) ->
 handle_event(_Event, State) ->
     {ok, State}.
 
+%% @private
 handle_info(_Info, State) ->
     {ok, State}.
 
+%% @private
 terminate(_Reason, State) ->
     %% flush and close any file handles
     lists:foreach(
@@ -107,6 +117,7 @@ terminate(_Reason, State) ->
             (_) -> ok
         end, State#state.files).
 
+%% @private
 code_change(_OldVsn, State, _Extra) ->
     {ok, State}.
 

src/lager_handler_watcher.erl

@@ -1,3 +1,24 @@
+%% Copyright (c) 2011 Basho Technologies, Inc.  All Rights Reserved.
+%%
+%% This file is provided to you under the Apache License,
+%% Version 2.0 (the "License"); you may not use this file
+%% except in compliance with the License.  You may obtain
+%% a copy of the License at
+%%
+%%   http://www.apache.org/licenses/LICENSE-2.0
+%%
+%% Unless required by applicable law or agreed to in writing,
+%% software distributed under the License is distributed on an
+%% "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+%% KIND, either express or implied.  See the License for the
+%% specific language governing permissions and limitations
+%% under the License.
+
+%% @doc A process that does a gen_event:add_sup_handler and attempts to re-add
+%% event handlers when they exit.
+
+%% @private
+
 -module(lager_handler_watcher).
 
 -behaviour(gen_server).

src/lager_handler_watcher_sup.erl

@@ -14,6 +14,10 @@
 %% specific language governing permissions and limitations
 %% under the License.
 
+%% @doc A supervisor for monitoring lager_handler_watcher processes.
+
+%% @private
+
 -module(lager_handler_watcher_sup).
 
 -behaviour(supervisor).

src/lager_sup.erl

@@ -14,6 +14,10 @@
 %% specific language governing permissions and limitations
 %% under the License.
 
+%% @doc Lager's top level supervisor.
+
+%% @private
+
 -module(lager_sup).
 
 -behaviour(supervisor).

src/lager_transform.erl

@@ -14,18 +14,20 @@
 %% specific language governing permissions and limitations
 %% under the License.
 
+%% @doc The parse transform used for lager messages.
+%% This parse transform rewrites functions calls to lager:Severity/1,2 into
+%% a more complicated function that captures module, function, line, pid and
+%% time as well. The entire function call is then wrapped in a case that
+%% checks the mochiglobal 'loglevel' value, so the code isn't executed if
+%% nothing wishes to consume the message.
+
 -module(lager_transform).
 -export([parse_transform/2]).
 
 -define(LEVELS, [debug, info, notice, warning, error, critical, alert,
         emergency]).
 
-%% This parse transform rewrites functions calls to lager:Severity/1,2 into
-%% a more complicated function that captures module, function, line, pid and
-%% time as well. The entire function call is then wrapped in a case that
-%$ checks the mochiglobal 'loglevel' value, so the code isn't executed if
-%% nothing wishes to consume the message.
-
+%% @private
 parse_transform(AST, _Options) ->
     %io:format("~n~p~n", [AST]),
     walk_ast([], AST).