* src/*.erl: Fix EDoc comments

SVN Revision: 1771

ChangeLog

@@ -1,3 +1,7 @@
+2009-01-03  Badlop  <badlop@process-one.net>
+
+	* src/*.erl: Fix EDoc comments
+
 2009-01-03  Christophe Romain <christophe.romain@process-one.net>
 
 	* src/mod_pubsub/mod_pubsub.erl: deliver notification depending on

src/ejabberd_app.erl

@@ -163,7 +163,7 @@ connect_nodes() ->
     end.
 
 %% @spec () -> string()
-%% Returns the full path to the ejabberd log file.
+%% @doc Returns the full path to the ejabberd log file.
 %% It first checks for application configuration parameter 'log_path'.
 %% If not defined it checks the environment variable EJABBERD_LOG_PATH.
 %% And if that one is neither defined, returns the default value:

src/ejabberd_auth.erl

@@ -260,7 +260,7 @@ is_user_exists_in_other_modules(Module, User, Server) ->
       end, auth_modules(Server)--[Module]).
 
 %% @spec (User, Server) -> ok | error | {error, not_allowed}
-%% Remove user.
+%% @doc Remove user.
 %% Note: it may return ok even if there was some problem removing the user.
 remove_user(User, Server) ->
     R = lists:foreach(
@@ -274,7 +274,7 @@ remove_user(User, Server) ->
     R.
 
 %% @spec (User, Server, Password) -> ok | not_exists | not_allowed | bad_request | error
-%% Try to remove user if the provided password is correct.
+%% @doc Try to remove user if the provided password is correct.
 %% The removal is attempted in each auth method provided:
 %% when one returns 'ok' the loop stops;
 %% if no method returns 'ok' then it returns the error message indicated by the last method attempted.

src/ejabberd_auth_internal.erl

@@ -239,7 +239,7 @@ is_user_exists(User, Server) ->
     end.
 
 %% @spec (User, Server) -> ok
-%% Remove user.
+%% @doc Remove user.
 %% Note: it returns ok even if there was some problem removing the user.
 remove_user(User, Server) ->
     LUser = jlib:nodeprep(User),
@@ -252,7 +252,7 @@ remove_user(User, Server) ->
 	ok.
 
 %% @spec (User, Server, Password) -> ok | not_exists | not_allowed | bad_request
-%% Remove user if the provided password is correct.
+%% @doc Remove user if the provided password is correct.
 remove_user(User, Server, Password) ->
     LUser = jlib:nodeprep(User),
     LServer = jlib:nameprep(Server),

src/ejabberd_auth_odbc.erl

@@ -220,7 +220,7 @@ is_user_exists(User, Server) ->
     end.
 
 %% @spec (User, Server) -> ok | error
-%% Remove user.
+%% @doc Remove user.
 %% Note: it may return ok even if there was some problem removing the user.
 remove_user(User, Server) ->
     case jlib:nodeprep(User) of
@@ -234,7 +234,7 @@ remove_user(User, Server) ->
     end.
 
 %% @spec (User, Server, Password) -> ok | error | not_exists | not_allowed
-%% Remove user if the provided password is correct.
+%% @doc Remove user if the provided password is correct.
 remove_user(User, Server, Password) ->
     case jlib:nodeprep(User) of
 	error ->

src/ejabberd_ctl.erl

@@ -226,8 +226,7 @@ process2(Args) ->
 %% Command calling
 %%-----------------------------
 
-%% @spec (Args::[string()]) ->
+%% @spec (Args::[string()]) -> string() | integer() | {string(), integer()}
-%%       String::string() | Code::integer() | {String::string(), Code::integer()}
 try_run_ctp(Args) ->
     try ejabberd_hooks:run_fold(ejabberd_ctl_process, false, [Args]) of
 	false when Args /= [] ->
@@ -248,8 +247,7 @@ try_run_ctp(Args) ->
 	    {io_lib:format("Error in ejabberd ctl process: '~p' ~p", [Error, Why]), ?STATUS_USAGE}
     end.
 
-%% @spec (Args::[string()]) ->
+%% @spec (Args::[string()]) -> string() | integer() | {string(), integer()}
-%%       String::string() | Code::integer() | {String::string(), Code::integer()}
 try_call_command(Args) ->
     try call_command(Args) of
 	{error, command_unknown} ->
@@ -264,8 +262,7 @@ try_call_command(Args) ->
 	    {io_lib:format("Problem '~p ~p' occurred executing the command.~nStacktrace: ~p", [A, Why, Stack]), ?STATUS_ERROR}
     end.
 
-%% @spec (Args::[string()]) ->
+%% @spec (Args::[string()]) -> string() | integer() | {string(), integer()} | {error, ErrorType}
-%%       String::string() | Code::integer() | {String::string(), Code::integer()} | {error, ErrorType}
 call_command([CmdString | Args]) ->
     {ok, CmdStringU, _} = regexp:gsub(CmdString, "-", "_"),
     Command = list_to_atom(CmdStringU),

src/mod_last.erl

@@ -174,7 +174,7 @@ store_last_info(User, Server, TimeStamp, Status) ->
 	end,
     mnesia:transaction(F).
 
-%% @spec (LUser::string(), LServer::string() ->
+%% @spec (LUser::string(), LServer::string()) ->
 %%      {ok, Timestamp::integer(), Status::string()} | not_found
 get_last_info(LUser, LServer) ->
     case catch mnesia:dirty_read(last_activity, {LUser, LServer}) of

src/mod_last_odbc.erl

@@ -168,7 +168,7 @@ store_last_info(User, Server, TimeStamp, Status) ->
     State = ejabberd_odbc:escape(Status),
     odbc_queries:set_last_t(LServer, Username, Seconds, State).
 
-%% @spec (LUser::string(), LServer::string() ->
+%% @spec (LUser::string(), LServer::string()) ->
 %%      {ok, Timestamp::integer(), Status::string()} | not_found
 get_last_info(LUser, LServer) ->
     Username = ejabberd_odbc:escape(LUser),

src/mod_pubsub/mod_pubsub.erl

@@ -33,7 +33,7 @@
 %%% This module uses version 1.12 of the specification as a base.
 %%% Most of the specification is implemented.
 %%% Functions concerning configuration should be rewritten.
-%%% Code is derivated from the original pubsub v1.7, by Alexey Shchepin <alexey@process-one.net>
+%%% Code is derivated from the original pubsub v1.7, by Alexey Shchepin
 
 %%% TODO
 %%% plugin: generate Reply (do not use broadcast atom anymore)
@@ -1753,10 +1753,11 @@ get_items(Host, Node, From) ->
 send_last_item(Host, Node, LJID) ->
     send_items(Host, Node, LJID, last).
 
-%% @spec (Host, Node, LJID) -> any()
+%% @spec (Host, Node, LJID, Number) -> any()
 %%	 Host = host()
 %%	 Node = pubsubNode()
 %%	 LJID = {U, S, []}
+%%	 Number = last | integer()
 %% @doc <p>Resend the items of a node to the user.</p>
 %% @todo use cache-last-item feature
 send_items(Host, Node, LJID, Number) ->
@@ -2139,10 +2140,9 @@ is_to_deliver({User, Server, _}, _, true) ->
 	end, false, Ss)
     end.
 
-%% @spec (Elem, Payload) -> int()
+%% @spec (Payload) -> int()
-%%	Elem = atom()
 %%	Payload = term()
-%% @doc <p>Count occurence of given element in payload.</p>
+%% @doc <p>Count occurence of XML elements in payload.</p>
 payload_xmlelements(Payload) -> payload_xmlelements(Payload, 0).
 payload_xmlelements([], Count) -> Count;
 payload_xmlelements([{xmlelement, _, _, _}|Tail], Count) -> payload_xmlelements(Tail, Count+1);
@@ -2150,7 +2150,7 @@ payload_xmlelements([_|Tail], Count) -> payload_xmlelements(Tail, Count).
 
 %% @spec (Els) -> stanza()
 %%	Els = [xmlelement()]
-%% @doc <p>Build pubsub event stanza
+%% @doc <p>Build pubsub event stanza</p>
 event_stanza(Els) ->
     {xmlelement, "message", [],
      [{xmlelement, "event", [{"xmlns", ?NS_PUBSUB_EVENT}], Els}]}.

src/mod_pubsub/node_default.erl

@@ -645,7 +645,7 @@ set_state(_) ->
 del_state(StateId) ->
     mnesia:delete({pubsub_state, StateId}).
 
-%% @spec (Host, Node) -> [Items] | []
+%% @spec (Host, Node, From) -> [Items] | []
 %%	 Host = mod_pubsub:host()
 %%	 Node = mod_pubsub:pubsubNode()
 %%	 Items = mod_pubsub:pubsubItems()
@@ -760,7 +760,7 @@ set_item(Item) when is_record(Item, pubsub_item) ->
 set_item(_) ->
     {error, ?ERR_INTERNAL_SERVER_ERROR}.
 
-%% @spec (ItemId) -> ok | {error, Reason::stanzaError()}
+%% @spec (Host, Node, ItemId) -> ok | {error, Reason::stanzaError()}
 %%	 Host = mod_pubsub:host()
 %%	 Node = mod_pubsub:pubsubNode()
 %%	 ItemId = string()

src/mod_pubsub/node_mb.erl

@@ -30,6 +30,7 @@
 %%%   	  {plugins, ["default", "pep","mb"]},
 %%%	  {pep_mapping, [{"urn:xmpp:microblog", "mb"}]}
 %%%   	 ]},
+%%% </p>
 %%% <p>PubSub plugin nodes are using the {@link gen_pubsub_node} behaviour.</p>
 
 -module(node_mb).

src/mod_pubsub/nodetree_default.erl

@@ -96,12 +96,12 @@ set_node(Record) when is_record(Record, pubsub_node) ->
 set_node(_) ->
     {error, ?ERR_INTERNAL_SERVER_ERROR}.
 
-%% @spec (Host, Node) -> pubsubNode() | {error, Reason}
-%%     Host = mod_pubsub:host()
-%%     Node = mod_pubsub:pubsubNode()
 get_node(Host, Node, _From) ->
     get_node(Host, Node).
 
+%% @spec (Host, Node) -> pubsubNode() | {error, Reason}
+%%     Host = mod_pubsub:host()
+%%     Node = mod_pubsub:pubsubNode()
 get_node(Host, Node) ->
     case catch mnesia:read({pubsub_node, {Host, Node}}) of
 	[Record] when is_record(Record, pubsub_node) -> Record;
@@ -109,11 +109,11 @@ get_node(Host, Node) ->
 	Error -> Error
     end.
 
-%% @spec (Key) -> [pubsubNode()] | {error, Reason}
-%%     Key = mod_pubsub:host() | mod_pubsub:jid()
 get_nodes(Key, _From) ->
     get_nodes(Key).
 
+%% @spec (Key) -> [pubsubNode()] | {error, Reason}
+%%     Key = mod_pubsub:host() | mod_pubsub:jid()
 get_nodes(Key) ->
     mnesia:match_object(#pubsub_node{nodeid = {Key, '_'}, _ = '_'}).
 

src/mod_pubsub/nodetree_virtual.erl

@@ -83,24 +83,24 @@ options() ->
 set_node(_NodeRecord) ->
     ok.
 
+get_node(Host, Node, _From) ->
+    get_node(Host, Node).
+
 %% @spec (Host, Node) -> pubsubNode()
 %%     Host = mod_pubsub:host()
 %%     Node = mod_pubsub:pubsubNode()
 %% @doc <p>Virtual node tree does not handle a node database. Any node is considered
 %% as existing. Node record contains default values.</p>
-get_node(Host, Node, _From) ->
-    get_node(Host, Node).
-
 get_node(Host, Node) ->
     #pubsub_node{nodeid = {Host, Node}}.
 
+get_nodes(Key, _From) ->
+    get_nodes(Key).
+
 %% @spec (Key) -> [pubsubNode()]
 %%     Host = mod_pubsub:host() | mod_pubsub:jid()
 %% @doc <p>Virtual node tree does not handle a node database. Any node is considered
 %% as existing. Nodes list can not be determined.</p>
-get_nodes(Key, _From) ->
-    get_nodes(Key).
-
 get_nodes(_Key) ->
     [].
 

src/web/ejabberd_web_admin.erl

@@ -107,7 +107,7 @@ get_auth(Auth) ->
 make_xhtml(Els, Host, Lang) ->
     make_xhtml(Els, Host, cluster, Lang).
 
-%% @spec (Els, Host, Node, Lang)
+%% @spec (Els, Host, Node, Lang) -> {200, [html], xmlelement()}
 %% where Host = global | string()
 %%       Node = cluster | atom()
 make_xhtml(Els, Host, Node, Lang) ->