From 4417608b27598cf15e261de47f6d4f099e74f684 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jean-S=C3=A9bastien=20P=C3=A9dron?=
 <js.pedron@meetic-corp.com>
Date: Thu, 22 Jan 2009 15:54:03 +0000
Subject: [PATCH] Document every functions to clarify the types to give and
 returned.

PR:		EJABP-1

SVN Revision: 1846
---
 ChangeLog   |  3 ++
 src/acl.erl | 97 ++++++++++++++++++++++++++++++++++++++++++++++++-----
 2 files changed, 92 insertions(+), 8 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 9790c6b9e..7d721dd10 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -7,6 +7,9 @@
 	list_to_binary/1; now that exmpp_stringprep return the correct type,
 	it was used on a binary().
 
+	* src/acl.erl: Document every functions to clarify the types to
+	give and returned.
+
 2009-01-21  Jean-Sébastien Pédron  <js.pedron@meetic-corp.com>
 
 	* src/acl.erl (match_acl/3): Use string() version of
diff --git a/src/acl.erl b/src/acl.erl
index aa672b4bf..976d70a84 100644
--- a/src/acl.erl
+++ b/src/acl.erl
@@ -37,8 +37,38 @@
 
 -include("ejabberd.hrl").
 
+%% @type aclspec() = all | JID_Exact | JID_Regexp | JID_Glob | Shared_Group
+%%     JID_Exact = {user, U} | {user, U, S} | {server, S} | {resource, R}
+%%         U = string()
+%%         S = string()
+%%         R = string()
+%%     JID_Regexp = {user_regexp, UR} | {user_regexp, UR, S} | {server_regexp, SR} | {resource_regexp, RR} | {node_regexp, UR, SR}
+%%         UR = string()
+%%         SR = string()
+%%         RR = string()
+%%     JID_Glob = {user_glob, UG} | {user_glob, UG, S} | {server_glob, SG} | {resource_glob, RG} | {node_glob, UG, SG}
+%%         UG = string()
+%%         SG = string()
+%%         RG = string()
+%%     Shared_Group = {shared_group, G} | {shared_group, G, H}
+%%         G = string()
+%%         H = string().
+
+%% @type acl() = {acl, ACLName, ACLSpec}
+%%     ACLName = atom()
+%%     ACLSpec = aclspec().
+%% Record in its Ejabberd-configuration-file variant.
+
+%% @type storedacl() = {acl, {ACLName, Host}, ACLSpec}
+%%     ACLName = atom()
+%%     Host = global | string()
+%%     ACLSpec = aclspec().
+%% Record in its Mnesia-table-record variant.
+
 -record(acl, {aclname, aclspec}).
 
+%% @spec () -> ok
+
 start() ->
     mnesia:create_table(acl,
 			[{disc_copies, [node()]},
@@ -47,9 +77,20 @@ start() ->
     mnesia:add_table_copy(acl, node(), ram_copies),
     ok.
 
+%% @spec (Host, ACLName, ACLSpec) -> storedacl()
+%%     Host = global | string()
+%%     ACLName = atom()
+%%     ACLSpec = aclspec()
+
 to_record(Host, ACLName, ACLSpec) ->
     #acl{aclname = {ACLName, Host}, aclspec = normalize_spec(ACLSpec)}.
 
+%% @spec (Host, ACLName, ACLSpec) -> {atomic, ok} | {aborted, Reason}
+%%     Host = global | string()
+%%     ACLName = atom()
+%%     ACLSpec = all | none | aclspec()
+%%     Reason = term()
+
 add(Host, ACLName, ACLSpec) ->
     F = fun() ->
 		mnesia:write(#acl{aclname = {ACLName, Host},
@@ -57,6 +98,11 @@ add(Host, ACLName, ACLSpec) ->
 	end,
     mnesia:transaction(F).
 
+%% @spec (Host, ACLs, Clear) -> ok | false
+%%     Host = global | string()
+%%     ACLs = [acl()]
+%%     Clear = bool()
+
 add_list(Host, ACLs, Clear) ->
     F = fun() ->
 		if
@@ -86,8 +132,17 @@ add_list(Host, ACLs, Clear) ->
 	    false
     end.
 
-normalize(A) ->
-    exmpp_stringprep:nodeprep(A).
+%% @spec (String) -> Prepd_String
+%%     String = string()
+%%     Prepd_String = string()
+
+normalize(String) ->
+    exmpp_stringprep:nodeprep(String).
+
+%% @spec (ACLSpec) -> Normalized_ACLSpec
+%%     ACLSpec = all | none | aclspec()
+%%     Normalized_ACLSpec = aclspec()
+
 normalize_spec({A, B}) ->
     {A, normalize(B)};
 normalize_spec({A, B, C}) ->
@@ -99,6 +154,12 @@ normalize_spec(none) ->
 
 
 
+%% @spec (Host, Rule, JID) -> Access
+%%     Host = global | string()
+%%     Rule = all | none | atom()
+%%     JID = exmpp_jid:jid()
+%%     Access = allow | deny | atom()
+
 match_rule(global, Rule, JID) ->
     case Rule of
 	all -> allow;
@@ -143,18 +204,30 @@ match_rule(Host, Rule, JID) ->
 	    end
     end.
 
+%% @spec (ACLs, JID, Host) -> Access
+%%     ACLs = [{Access, ACLName}]
+%%         Access = deny | atom()
+%%         ACLName = atom()
+%%     JID = exmpp_jid:jid()
+%%     Host = string()
+
 match_acls([], _, _Host) ->
     deny;
-match_acls([{Access, ACL} | ACLs], JID, Host) ->
-    case match_acl(ACL, JID, Host) of
+match_acls([{Access, ACLName} | ACLs], JID, Host) ->
+    case match_acl(ACLName, JID, Host) of
 	true ->
 	    Access;
 	_ ->
 	    match_acls(ACLs, JID, Host)
     end.
 
-match_acl(ACL, JID, Host) ->
-    case ACL of
+%% @spec (ACLName, JID, Host) -> bool()
+%%     ACLName = all | none | atom()
+%%     JID = exmpp_jid:jid()
+%%     Host = string()
+
+match_acl(ACLName, JID, Host) ->
+    case ACLName of
 	all -> true;
 	none -> false;
 	_ ->
@@ -220,10 +293,14 @@ match_acl(ACL, JID, Host) ->
 				      false
 			      end
 		      end,
-		      ets:lookup(acl, {ACL, global}) ++
-		      ets:lookup(acl, {ACL, Host}))
+		      ets:lookup(acl, {ACLName, global}) ++
+		      ets:lookup(acl, {ACLName, Host}))
     end.
 
+%% @spec (String, RegExp) -> bool()
+%%     String = string()
+%%     RegExp = string()
+
 is_regexp_match(String, RegExp) ->
     case regexp:first_match(String, RegExp) of
 	nomatch ->
@@ -237,6 +314,10 @@ is_regexp_match(String, RegExp) ->
 	    false
     end.
 
+%% @spec (String, Glob) -> bool()
+%%     String = string()
+%%     Glob = string()
+
 is_glob_match(String, Glob) ->
     is_regexp_match(String, regexp:sh_to_awk(Glob)).