Permalink
Browse files

Comment style updated to conform to coding style.

Finsignia coding style uses foldmarks and vim directives in the comments
to separate out Erlang source files.  Most Erlang source files have
sections like:
* HEADER
* CALLBACKS
* PUBLIC API
* PRIVATE FUNCTIONS

Also document specifications added to some callback declarations as a
reminder to the application developer what interface is expected.
  • Loading branch information...
1 parent 277ceff commit 45c4d24cfcbd53a58a9e83093769fc574241707b @mbbx6spp committed Jan 31, 2011
Showing with 92 additions and 50 deletions.
  1. +7 −8 ctsuite.erl
  2. +27 −20 ejabberdmod.erl
  3. +16 −4 escript
  4. +11 −8 eunit.erl
  5. +31 −10 gen_event.erl
View
@@ -1,3 +1,4 @@
+%%%' HEADER
%%% @author {{author_name}} <{{author_email}}>
%%% @since {{date}}
%%% @copyright {{copyright_year}} {{author_name}}
@@ -8,10 +9,8 @@
%% Note: This directive should only be used in test suites.
-compile(export_all).
-include_lib("common_test/include/ct.hrl").
-
-%%--------------------------------------------------------------------
-%% COMMON TEST CALLBACK FUNCTIONS
-%%--------------------------------------------------------------------
+%%%.
+%%%' CALLBACKS
%% @spec suite() -> Config
%% where
@@ -102,9 +101,8 @@ groups() ->
all() ->
[my_test_case].
-%%--------------------------------------------------------------------
-%% TEST CASES
-%%--------------------------------------------------------------------
+%%%.
+%%%' TESTCASES
%% @spec TestCase() -> Info
%% where
@@ -123,4 +121,5 @@ my_test_case() ->
%% @doc the test function.
my_test_case(_Config) ->
ok.
-
+%%%.
+%%% vim: set filetype=erlang tabstop=2 foldmarker=%%%',%%%. foldmethod=marker:
View
@@ -1,28 +1,29 @@
-%% == mod_{{name}}.erl ==
+%%%' HEADER
%% @author {{author_name}} <{{author_name}}>
%% @copyright {{copyright_year}} {{author_name}}
%% @doc ejabberd module that ... listens to packets sent & received by users.
+%% @end
-module(mod_{{name}}).
-author('{{author_name}} <{{author_email}}>').
-behaviour(gen_mod).
-export([start/2, init/2, stop/1,
- send_packet/3, receive_packet/4]).
+ send_packet/3, receive_packet/4]).
--include("ejabberd.hrl").
--include("jlib.hrl").
+-include_lib("ejabberd/include/ejabberd.hrl").
+-include("ejabberd/include/jlib.hrl").
-define(PROCNAME, ejabberd_{{name}}).
-ifdef(TEST).
-compile(export_all).
-endif.
-%% -------------------
-%% Module control
-%% -------------------
+%%%.
+%%%' CALLBACKS
+
start(Host, Opts) ->
Opt1 = gen_mod:get_opt(opt1, Opts, "default value"),
% capture packets sent by user
@@ -47,39 +48,45 @@ init(Host, Opt1) ->
% do something here instead of nothing
loop(Host, Opt1).
-%% -------------------
-%% Loop
-%% -------------------
loop(Host, Opt1) ->
receive
{persist, E} ->
persist(E),
loop(Host, Opt1);
- stop ->
- ok;
- _ ->
- loop(Host, Opt1)
+ stop ->
+ ok;
+ _ ->
+ loop(Host, Opt1)
end.
-%% -------------------
-%% Public/Exported
-%% -------------------
+%%%.
+%%%' PUBLIC API
+
+%% @spec send_packet(FromJID, ToJID, P) -> ??
+%% @doc
+%% @end
send_packet(FromJID, ToJID, P) ->
Host = FromJID#jid.lserver,
Proc = gen_mod:get_module_proc(Host, ?PROCNAME),
Proc ! {persist, {send, FromJID, ToJID, P}}.
+%% @spec receive_packet(FromJID, ToJID, P) -> ??
+%% @doc
+%% @end
receive_packet(_JID, From, To, P) ->
Host = To#jid.lserver,
Proc = gen_mod:get_module_proc(Host, ?PROCNAME),
Proc ! {persist, {recv, From, To, P}}.
-%% -------------------
-%% Private
-%% -------------------
+%%%.
+%%%' PRIVATE FUNCTIONS
+
+%% @private
persist({recv, From, To, P}) ->
% do something with this data...like persist it somehow
ok;
persist({send, FromJID, ToJID, P}) ->
% do something with this data...like persist it somehow
ok.
+%%%.
+%%% vim: set filetype=erlang tabstop=2 foldmarker=%%%',%%%. foldmethod=marker:
View
20 escript
@@ -1,14 +1,26 @@
#!/usr/bin/env escript
%% -*- mode: erlang -*-
+%%%' HEADER
+%% @author {{author_name}} <{{author_email}}>
+%% @copyright {{copyright_year}} {{author_name}}
+%% @doc {{description}}
+%% @end
-export([main/1]).
-
-define(CMD, filename:basename(escript:script_name())).
-
-%% External API
-
+%%%.
+%%%' PUBLIC API
+%% @spec main(Args) -> void()
+%% where
+%% Args = [string()]
main(_)->
usage().
+%%%.
+%%%' PRIVATE FUNCTIONS
+%% @private
usage() ->
io:format("Usage: ~s ...~n", [?CMD]),
halt(1).
+
+%%%.
+%%% vim: set filetype=erlang tabstop=2 foldmarker=%%%',%%%. foldmethod=marker:
View
@@ -1,8 +1,8 @@
-%%%----------------------------------------------------------------------
-%% @author {{author_name}} <{{author_name}}>
+%%%' HEADER
+%% @author {{author_name}} <{{author_name}}>
%% @copyright {{copyright_year}} {{author_name}}
-%% @doc EUnit test suite module {{module_name}}
-%%%----------------------------------------------------------------------
+%% @doc EUnit test suite module {{module_name}}.
+%% @end
-module({{module_name}}_tests).
-author('{{author_name}} <{{author_email}}>').
@@ -12,10 +12,11 @@
-include_lib("eunit/include/eunit.hrl").
-define(MODNAME, {{module_name}}).
-
-%% ------------------------
-%% Test generating function
-%% ------------------------
+%%%.
+%%%' TEST GENERATOR
+%% @spec {{module_name}}_test_() -> List
+%% where
+%% List = [term()]
{{module_name}}_test_() ->
%% add your asserts in the returned list, e.g.:
%% [
@@ -27,4 +28,6 @@
%% ?assertThrow({not_found, _}, ?MODNAME:func(unknown_object))
%% ]
[].
+%%%.
+%%% vim: set filetype=erlang tabstop=2 foldmarker=%%%',%%%. foldmethod=marker:
View
@@ -1,8 +1,8 @@
-%%%----------------------------------------------------------------------
-%% @author {{author_name}} <{{author_name}}>
-%% @copyright {{copyright_year}} {{author_name}}
-%% @doc gen_event that ...
-%%%----------------------------------------------------------------------
+%%%' HEADER
+%%% @author {{author_name}} <{{author_name}}>
+%%% @copyright {{copyright_year}} {{author_name}}
+%%% @doc gen_event that {{description}}
+%%% @end
-module({{name}}).
-author('{{author_name}} <{{author_email}}>').
@@ -13,15 +13,36 @@
-ifdef(TEST).
-compile(export_all).
-endif.
-
-% initializes gen_event
+%%%.
+%%%' CALLBACKS
+%% @private
+%% @spec init(Args0) -> {ok, Args1}
+%% where
+%% Args0 = Args1 = [term()]
+%% @doc initializes gen_event
init(Args) ->
{ok, Args}.
-% handle/log error event
-handle_event(Message, State) ->
+%% @private
+%% @spec handle_event(Event, State0) -> {ok, State1} | {ok, State1, hibernate} |
+%% {swap_handler, Args1, State1, Handler2, Args2} | remove_handler
+%% where
+%% Event = term()
+%% State0 = State1 = term()
+%% Args1 = Args2 = term()
+%% Handler2 = Module2 | {Module2, Id}
+%% Module2 = atom()
+%% Id = term()
+%% @doc handle/log event
+handle_event(_Message, State) ->
{ok, State}.
-% terminates gen_event
+%% @spec terminate(Args, State0) -> ok
+%% where
+%% State0 = term()
+%% Args = term() | {stop, Reason} | stop | remove_handler |
+%% {error, {'EXIT', Reason}} | {error, Term}
+%% Reason = Term = term()
+%% terminates gen_event
terminate(_Args, _State) ->
ok.

0 comments on commit 45c4d24

Please sign in to comment.