Fix EDoc errors.

SVN Revision: 2495

src/cyrsasl.erl

@@ -42,12 +42,13 @@
 
 -record(sasl_mechanism, {mechanism, module, require_plain_password}).
 
-%% @type saslstate() = {sasl_state, Service, Myname, Realm, GetPassword, CheckPassword, Mech_Mod, Mech_State}
+%% @type saslstate() = {sasl_state, Service, Myname, Realm, GetPassword, CheckPassword, CheckPasswordDigest, Mech_Mod, Mech_State}
 %%     Service = string()
 %%     Myname = string()
 %%     Realm = string()
 %%     GetPassword = function()
 %%     CheckPassword = function()
+%%     CheckPasswordDigest = any()
 %%     Mech_Mod = atom()
 %%     Mech_State = term().
 %% State of this process.
@@ -148,7 +149,7 @@ listmech(Host) ->
 			 ['$1']}]),
     filter_anonymous(Host, Mechs).
 
-%% @spec (Service, ServerFQDN, UserRealm, SecFlags, GetPassword, CheckPassword) -> saslstate()
+%% @spec (Service, ServerFQDN, UserRealm, SecFlags, GetPassword, CheckPassword, CheckPasswordDigest) -> saslstate()
 %%     Service = string()
 %%     ServerFQDN = string()
 %%     UserRealm = string()

src/ejabberd_auth.erl

@@ -135,6 +135,7 @@ check_password_with_authmodule(User, Server, Password)
 %%     Digest = string() | undefined
 %%     DigestGen = function()
 %%     AuthModule = authmodule()
+%% @doc Check the password is valid and also return the authentication module that accepts it.
 %% The password is 'undefined' if the client
 %% authenticates using the digest method as defined in 
 %% XEP-0078: Non-SASL Authentication

src/ejabberd_auth_external.erl

@@ -124,11 +124,10 @@ get_password(_User, _Server) ->
 get_password_s(_User, _Server) ->
     "".
 
-%% @spec (User, Server) -> bool()
+%% @spec (User, Server) -> true | false | {error, Error}
 %%     User = string()
 %%     Server = string()
 
-%% @spec (User, Server) -> true | false | {error, Error}
 is_user_exists(User, Server) ->
     try extauth:is_user_exists(User, Server) of
 	Res -> Res

src/ejabberd_auth_internal.erl

@@ -361,11 +361,10 @@ get_password_s(User, Server) ->
 	    []
     end.
 
-%% @spec (User, Server) -> bool()
+%% @spec (User, Server) -> true | false | {error, Error}
 %%     User = string()
 %%     Server = string()
 
-%% @spec (User, Server) -> true | false | {error, Error}
 is_user_exists(User, Server) ->
     try
 	LUser = exmpp_stringprep:nodeprep(User),

src/ejabberd_auth_ldap.erl

@@ -241,11 +241,10 @@ get_password(_User, _Server) ->
 get_password_s(_User, _Server) ->
     "".
 
-%% @spec (User, Server) -> bool()
+%% @spec (User, Server) -> true | false | {error, Error}
 %%     User = string()
 %%     Server = string()
 
-%% @spec (User, Server) -> true | false | {error, Error}
 is_user_exists(User, Server) ->
     case catch is_user_exists_ldap(User, Server) of
 	{'EXIT', Error} ->

src/ejabberd_auth_odbc.erl

@@ -286,11 +286,10 @@ get_password_s(User, Server) ->
 	    ""
     end.
 
-%% @spec (User, Server) -> bool()
+%% @spec (User, Server) -> true | false | {error, Error}
 %%     User = string()
 %%     Server = string()
 
-%% @spec (User, Server) -> true | false | {error, Error}
 is_user_exists(User, Server) ->
     try
 	LUser = exmpp_stringprep:nodeprep(User),

src/ejabberd_commands.erl

@@ -290,12 +290,12 @@ get_command_definition(Name) ->
 execute_command(Name, Arguments) ->
     execute_command([], noauth, Name, Arguments).
 
-%% @spec (AccessCommands, AuthList, Name::atom(), Arguments) -> ResultTerm | {error, Error}
+%% @spec (AccessCommands, Auth, Name::atom(), Arguments) -> ResultTerm | {error, Error}
 %% where 
 %%       AccessCommands = [{Access, CommandNames, Arguments}]
-%%       Auth = {user, string()}, {server, string()}, {password, string()} | noauth
+%%       Auth = {User::string(), Server::string(), Password::string()} | noauth
 %%       Method = atom()
-%%       Arguments = [...]
+%%       Arguments = [any()]
 %%       Error = command_unknown | account_unprivileged | invalid_account_data | no_auth_provided
 execute_command(AccessCommands, Auth, Name, Arguments) ->
     case ets:lookup(ejabberd_commands, Name) of
@@ -346,14 +346,15 @@ get_tags_commands() ->
 %% Access verification
 %% -----------------------------
 
-%% At least one AccessCommand must be satisfied
 %% @spec (AccessCommands, Auth, Method, Command, Arguments) -> ok
 %% where 
 %%       AccessCommands =  [ {Access, CommandNames, Arguments} ]
-%%       Auth = {User::string(), Server::string(), Password::string()}
+%%       Auth = {User::string(), Server::string(), Password::string()} | noauth
 %%       Method = atom()
-%%       Arguments = [...]
+%%       Arguments = [any()]
-%% It may throw {error, Error} where
+%% @doc Check access is allowed to that command.
+%% At least one AccessCommand must be satisfied.
+%% It may throw {error, Error} where:
 %% Error = account_unprivileged | invalid_account_data | no_auth_provided
 check_access_commands([], _Auth, _Method, _Command, _Arguments) ->
     ok;

src/ejabberd_ctl.erl

@@ -275,7 +275,7 @@ try_call_command(Args, Auth, AccessCommands) ->
 	    {io_lib:format("Problem '~p ~p' occurred executing the command.~nStacktrace: ~p", [A, Why, Stack]), ?STATUS_ERROR}
     end.
 
-%% @spec (Args::[string()], Auth) -> string() | integer() | {string(), integer()} | {error, ErrorType}
+%% @spec (Args::[string()], Auth, AccessCommands) -> string() | integer() | {string(), integer()} | {error, ErrorType}
 call_command([CmdString | Args], Auth, AccessCommands) ->
     {ok, CmdStringU, _} = regexp:gsub(CmdString, "-", "_"),
     Command = list_to_atom(CmdStringU),

src/ejabberd_piefxis.erl

@@ -162,11 +162,8 @@ add_user(El, Domain) ->
     Password = exmpp_xml:get_attribute(El,password,none),
     add_user(El, Domain, User, Password).
 
-%% @spec El = XML element
+%% @spec (El::xmlel(), Domain::string(), User::string(), Password::string())
-%%       Domain = String with a domain name
+%%       -> ok | {atomic, exists} | {error, not_allowed}
-%%       User = String with an user name
-%%       Password = String with an user password
-%% @ret ok | {atomic, exists} | {error, not_allowed}
 %% @doc Add a new user to the database.
 %% If user already exists, it will be only updated.
 add_user(El, Domain, User, Password) ->
@@ -191,10 +188,8 @@ add_user(El, Domain, User, Password) ->
 	    ?ERROR_MSG("Error adding user ~s@~s: ~p~n", [User, Domain, Other])
     end.
 
-%% @spec User = String with User name
+%% @spec (User::string(), Password::string(), Domain::string())
-%%       Password = String with a Password value
+%%       -> ok | {atomic, exists} | {error, not_allowed}
-%%       Domain = Stirng with a Domain name
-%% @ret  ok | {atomic, exists} | {error, not_allowed}
 %% @doc  Create a new user
 create_user(User,Password,Domain) ->
     case ejabberd_auth:try_register(?BTL(User),?BTL(Domain),?BTL(Password)) of
@@ -207,14 +202,13 @@ create_user(User,Password,Domain) ->
 %%%==================================
 %%%% Populate user
 
-%% @spec User = String
+%% @spec (User::string(), Domain::string(), El::xml())
-%%       Domain = String
+%%      -> ok | {error, not_found}
-%%       El = XML element
-%% @ret  ok | {error, not_found}
 %%
 %% @doc  Add a new user from a XML file with a roster list.
 %%
 %% Example of a file:
+%% ```
 %% <?xml version='1.0' encoding='UTF-8'?>
 %% <server-data xmlns='http://www.xmpp.org/extensions/xep-0227.html#ns'>
 %%   <host jid='localhost'>
@@ -229,6 +223,7 @@ create_user(User,Password,Domain) ->
 %%     </user>
 %%   </host>
 %%  </server-data>
+%% '''
 
 populate_user(User,Domain,El=#xmlel{name='query', ns='jabber:iq:roster'}) ->
     io:format("Trying to add/update roster list...",[]),
@@ -258,6 +253,7 @@ populate_user(User,Domain,El=#xmlel{name='query', ns='jabber:iq:roster'}) ->
 %% @doc  Read vcards from the XML and send it to the server
 %%
 %% Example:
+%% ```
 %% <?xml version='1.0' encoding='UTF-8'?>
 %% <server-data xmlns='http://www.xmpp.org/extensions/xep-0227.html#ns'>
 %%   <host jid='localhost'>
@@ -268,6 +264,7 @@ populate_user(User,Domain,El=#xmlel{name='query', ns='jabber:iq:roster'}) ->
 %%     </user>
 %%   </host>
 %% </server-data>
+%% '''
 
 populate_user(User,Domain,El=#xmlel{name='vCard', ns='vcard-temp'}) ->
     io:format("Trying to add/update vCards...",[]),
@@ -457,7 +454,7 @@ make_xinclude(Fn) ->
 %%%% Export user
 
 %% @spec (Fd, Username::string(), Host::string()) -> ok
-%% extraer su informacion e imprimirla
+%% @doc Extract user information and print it.
 export_user(Fd, Username, Host) ->
     UserString = extract_user(Username, Host),
     print(Fd, UserString).
@@ -613,9 +610,8 @@ make_main_basefilename(Dir, FnT) ->
     filename:join([Dir, Filename2]).
 
 %% @spec (FnT::string(), Host::string()) -> FnH::string()
-%% FnH = FnT + _ + Host2 + Extension
+%% @doc Make the filename for the host.
-%% Host2 = Host with any . replaced by _
+%% Example: ``("20080804-231550", "jabber.example.org") -> "20080804-231550_jabber_example_org.xml"''
-%% Example: ("20080804-231550", "jabber.example.org") -> "20080804-231550_jabber_example_org.xml"
 make_host_filename(FnT, Host) ->
     Host2 = string:join(string:tokens(Host, "."), "_"),
     filename:flatten([FnT, "_", Host2, ".xml"]).

src/mod_roster.erl

@@ -182,13 +182,11 @@ roster_hash(Items) ->
 			[R#roster{groups = lists:sort(Grs)} || 
 				R = #roster{groups = Grs} <- Items]))).
 		
-%% @spec (Host) -> true | false
+%% @spec (Host::binary()) -> true | false
-%% @type Host = binary()
 roster_versioning_enabled(Host)  ->
 	gen_mod:get_module_opt(binary_to_list(Host), ?MODULE, versioning, false).
 
-%% @spec (Host) -> true | false
+%% @spec (Host::binary()) -> true | false
-%% @type Host = binary()
 roster_version_on_db(Host) ->
 	gen_mod:get_module_opt(binary_to_list(Host), ?MODULE, store_current_id, false).
 
@@ -219,7 +217,7 @@ roster_version(LServer ,LUser) ->
 %%     To = exmpp_jid:jid()
 %%     IQ_Rec = exmpp_iq:iq()
 %%     IQ_Result = exmpp_iq:iq()
-%% Load roster from DB only if neccesary
+%% @doc Load roster from DB only if neccesary.
 %% It is neccesary if
 %%  	- roster versioning is disabled in server OR
 %%	- roster versioning is not used by the client OR

src/mod_roster_odbc.erl

@@ -140,13 +140,11 @@ roster_hash(Items) ->
 			[R#roster{groups = lists:sort(Grs)} || 
 				R = #roster{groups = Grs} <- Items]))).
 		
-%% @spec (Host) -> true | false
+%% @spec (Host::binary()) -> true | false
-%% @type Host = binary()
 roster_versioning_enabled(Host)  ->
 	gen_mod:get_module_opt(binary_to_list(Host), ?MODULE, versioning, false).
 
-%% @spec (Host) -> true | false
+%% @spec (Host::binary()) -> true | false
-%% @type Host = binary()
 roster_version_on_db(Host) ->
 	gen_mod:get_module_opt(binary_to_list(Host), ?MODULE, store_current_id, false).
 

src/web/mod_http_fileserver.erl

@@ -167,7 +167,8 @@ initialize(Host, Opts) ->
 %% @spec (AdminCTs::[CT], Default::[CT]) -> [CT]
 %% where CT = {Extension::string(), Value}
 %%       Value = string() | undefined
-%% Returns a unified list without duplicates where elements of AdminCTs have more priority.
+%% @doc Return a unified list without duplicates.
+%% Elements of AdminCTs have more priority.
 %% If a CT is declared as 'undefined', then it is not included in the result.
 build_list_content_types(AdminCTsUnsorted, DefaultCTsUnsorted) ->
     AdminCTs = lists:ukeysort(1, AdminCTsUnsorted),