Fix errors and warnings for "rebar3 edoc"

src/ejabberd.erl

@@ -52,7 +52,7 @@ halt() ->
     ejabberd_logger:flush(),
     erlang:halt(1, [{flush, true}]).
 
-%% @spec () -> false | string()
+-spec get_pid_file() -> false | string().
 get_pid_file() ->
     case os:getenv("EJABBERD_PID_PATH") of
 	false ->

src/ejabberd_auth_ldap.erl

@@ -151,7 +151,6 @@ get_users(Server, []) ->
 count_users(Server, Opts) ->
     length(get_users(Server, Opts)).
 
-%% @spec (User, Server) -> true | false | {error, Error}
 user_exists(User, Server) ->
     case catch user_exists_ldap(User, Server) of
 	{'EXIT', _Error} -> {nocache, {error, db_failure}};

src/ejabberd_ctl.erl

@@ -218,11 +218,11 @@ process(Args, Version) ->
     end,
     Code.
 
-%% @spec (Args::[string()], AccessCommands) -> {String::string(), Code::integer()}
+-spec process2(Args::[string()], AccessCommands::any()) ->
+    {String::string(), Code::integer()}.
 process2(Args, AccessCommands) ->
     process2(Args, AccessCommands, ?DEFAULT_VERSION).
 
-%% @spec (Args::[string()], AccessCommands, Version) -> {String::string(), Code::integer()}
 process2(["--auth", User, Server, Pass | Args], AccessCommands, Version) ->
     process2(Args, AccessCommands, {list_to_binary(User), list_to_binary(Server),
 				    list_to_binary(Pass), true}, Version);
@@ -271,7 +271,6 @@ determine_string_type(String, Version) ->
 %% Command calling
 %%-----------------------------
 
-%% @spec (Args::[string()], Auth, AccessCommands, Version) -> string() | integer() | {string(), integer()}
 try_run_ctp(Args, Auth, AccessCommands, Version) ->
     try ejabberd_hooks:run_fold(ejabberd_ctl_process, false, [Args]) of
 	false when Args /= [] ->
@@ -292,7 +291,6 @@ try_run_ctp(Args, Auth, AccessCommands, Version) ->
 	    {io_lib:format("Error in ejabberd ctl process: '~p' ~p", [Error, Why]), ?STATUS_USAGE}
     end.
 
-%% @spec (Args::[string()], Auth, AccessCommands, Version) -> string() | integer() | {string(), integer()}
 try_call_command(Args, Auth, AccessCommands, Version) ->
     try call_command(Args, Auth, AccessCommands, Version) of
 	{Reason, wrong_command_arguments} ->
@@ -316,7 +314,11 @@ try_call_command(Args, Auth, AccessCommands, Version) ->
 	     ?STATUS_ERROR}
     end.
 
-%% @spec (Args::[string()], Auth, AccessCommands, Version) -> string() | integer() | {string(), integer()} | {error, ErrorType}
+-spec call_command(Args::[string()],
+                   Auth::noauth | {binary(), binary(), binary(), true},
+                   AccessCommands::[any()],
+                   Version::integer()) ->
+    string() | integer() | {string(), integer()} | {error, ErrorType::any()}.
 call_command([CmdString | Args], Auth, _AccessCommands, Version) ->
     CmdStringU = ejabberd_regexp:greplace(
                    list_to_binary(CmdString), <<"-">>, <<"_">>),
@@ -768,7 +770,8 @@ print_usage_help(MaxC, ShCode) ->
 %% Print usage command
 %%-----------------------------
 
-%% @spec (CmdSubString::string(), MaxC::integer(), ShCode::boolean(), Version) -> ok
+-spec print_usage_commands2(CmdSubString::string(), MaxC::integer(),
+                            ShCode::boolean(), Version::integer()) -> ok.
 print_usage_commands2(CmdSubString, MaxC, ShCode, Version) ->
     %% Get which command names match this substring
     AllCommandsNames = [atom_to_list(Name) || {Name, _, _} <- ejabberd_commands:list_commands(Version)],
@@ -814,7 +817,8 @@ filter_commands_regexp(All, Glob) ->
       end,
       All).
 
-%% @spec (Cmd::string(), MaxC::integer(), ShCode::boolean(), Version) -> ok
+-spec print_usage_command(Cmd::string(), MaxC::integer(),
+                          ShCode::boolean(), Version::integer()) -> ok.
 print_usage_command(Cmd, MaxC, ShCode, Version) ->
     Name = list_to_atom(Cmd),
     C = ejabberd_commands:get_command_definition(Name, Version),

src/ejabberd_logger.erl

@@ -113,7 +113,6 @@ get_string_env(Name, Default) ->
             Default
     end.
 
--spec start() -> ok.
 start() ->
     start(info).
 
@@ -181,17 +180,14 @@ do_start(Level) ->
 			  lager:set_loghwm(Handler, LogRateLimit)
 		  end, gen_event:which_handlers(lager_event)).
 
--spec restart() -> ok.
 restart() ->
     Level = ejabberd_option:loglevel(),
     application:stop(lager),
     start(Level).
 
--spec reopen_log() -> ok.
 reopen_log() ->
     ok.
 
--spec rotate_log() -> ok.
 rotate_log() ->
     catch lager_crash_log ! rotate,
     lists:foreach(
@@ -201,7 +197,6 @@ rotate_log() ->
               ok
       end, gen_event:which_handlers(lager_event)).
 
--spec get() -> loglevel().
 get() ->
     Handlers = get_lager_handlers(),
     lists:foldl(fun(lager_console_backend, _Acc) ->
@@ -213,7 +208,6 @@ get() ->
                 end,
                 none, Handlers).
 
--spec set(0..5 | loglevel()) -> ok.
 set(N) when is_integer(N), N>=0, N=<5 ->
     set(convert_loglevel(N));
 set(Level) when ?is_loglevel(Level) ->
@@ -255,7 +249,6 @@ get_lager_version() ->
 	false -> "0.0.0"
     end.
 
--spec flush() -> ok.
 flush() ->
     application:stop(lager),
     application:stop(sasl).

src/ejabberd_piefxis.erl

@@ -642,33 +642,26 @@ make_host_filename(FnT, Host) ->
 make_host_basefilename(Dir, FnT) ->
     filename:join([Dir, FnT]).
 
-%% @spec () -> string()
 make_piefxis_xml_head() ->
     "<?xml version='1.0' encoding='UTF-8'?>".
 
-%% @spec () -> string()
 make_piefxis_xml_tail() ->
     "".
 
-%% @spec () -> string()
 make_piefxis_server_head() ->
     io_lib:format("<server-data xmlns='~ts' xmlns:xi='~ts'>",
                   [?NS_PIE, ?NS_XI]).
 
-%% @spec () -> string()
 make_piefxis_server_tail() ->
     "</server-data>".
 
-%% @spec (Host::string()) -> string()
 make_piefxis_host_head(Host) ->
     io_lib:format("<host xmlns='~ts' xmlns:xi='~ts' jid='~ts'>",
                   [?NS_PIE, ?NS_XI, Host]).
 
-%% @spec () -> string()
 make_piefxis_host_tail() ->
     "</host>".
 
-%% @spec (Fn::string()) -> string()
 make_xinclude(Fn) ->
     Base = filename:basename(Fn),
     io_lib:format("<xi:include href='~ts'/>", [Base]).

src/ejabberd_s2s.erl

@@ -589,10 +589,8 @@ allow_host1(MyHost, S2SHost) ->
             end
     end.
 
-%% Get information about S2S connections of the specified type.
-%% @spec (Type) -> [Info]
-%% where Type = in | out
-%%       Info = [{InfoName::atom(), InfoValue::any()}]
+%% @doc Get information about S2S connections of the specified type.
+-spec get_info_s2s_connections(Type::in | out) -> [[{InfoName::atom(), InfoValue::any()}]].
 get_info_s2s_connections(Type) ->
     ChildType = case Type of
 		    in -> ejabberd_s2s_in_sup;

src/ejabberd_sql.erl

@@ -488,8 +488,9 @@ run_sql_cmd(Command, From, State, Timestamp) ->
 	    abort_on_driver_error(outer_op(Command), From, Timestamp)
     end.
 
-%% Only called by handle_call, only handles top level operations.
-%% @spec outer_op(Op) -> {error, Reason} | {aborted, Reason} | {atomic, Result}
+%% @doc Only called by handle_call, only handles top level operations.
+-spec outer_op(Op::{atom(), binary()}) ->
+    {error, Reason::binary()} | {aborted, Reason::binary()} | {atomic, Result::any()}.
 outer_op({sql_query, Query}) ->
     sql_query_internal(Query);
 outer_op({sql_transaction, F}) ->

src/ejabberd_web_admin.erl

@@ -52,8 +52,8 @@
 %%%==================================
 %%%% get_acl_access
 
-%% @spec (Path::[string()], Method) -> {HostOfRule, [AccessRule]}
-%% where Method = 'GET' | 'POST'
+-spec get_acl_rule(Path::[binary()], 'GET' | 'POST') ->
+    {HostOfRule::binary(), [AccessRule::atom()]}.
 
 %% All accounts can access those URLs
 get_acl_rule([], _) -> {<<"localhost">>, [all]};
@@ -275,10 +275,13 @@ get_auth_account2(HostOfRule, AccessRule, User, Server,
 make_xhtml(Els, Host, Lang, JID, Level) ->
     make_xhtml(Els, Host, cluster, Lang, JID, Level).
 
-%% @spec (Els, Host, Node, Lang, JID, Level::integer()) -> {200, [html], xmlelement()}
-%% where Host = global | string()
-%%       Node = cluster | atom()
-%%       JID = jid()
+-spec make_xhtml([xmlel()],
+                 Host::global | binary(),
+                 Node::cluster | atom(),
+                 Lang::binary(),
+                 jid(),
+                 Level::integer()) ->
+    {200, [html], xmlel()}.
 make_xhtml(Els, Host, Node, Lang, JID, Level) ->
     Base = get_base_path_sum(0, 0, Level),
     MenuItems = make_navigation(Host, Node, Lang, JID, Level),
@@ -1877,18 +1880,15 @@ get_table_content(Node, Table, _Type, PageNumber, PageSize) ->
 %%%==================================
 %%%% navigation menu
 
-%% @spec (Host, Node, Lang, JID::jid(), Level::integer()) -> [LI]
 make_navigation(Host, Node, Lang, JID, Level) ->
     Menu = make_navigation_menu(Host, Node, Lang, JID, Level),
     make_menu_items(Lang, Menu).
 
-%% @spec (Host, Node, Lang, JID::jid(), Level::integer()) -> Menu
-%% where Host = global | string()
-%%       Node = cluster | string()
-%%       Lang = string()
-%%       Menu = {URL, Title} | {URL, Title, [Menu]}
-%%       URL = string()
-%%       Title = string()
+-spec make_navigation_menu(Host::global | binary(),
+                           Node::cluster | atom(),
+                           Lang::binary(), JID::jid(), Level::integer()) ->
+    Menu::{URL::binary(), Title::binary()}
+    | {URL::binary(), Title::binary(), [Menu::any()]}.
 make_navigation_menu(Host, Node, Lang, JID, Level) ->
     HostNodeMenu = make_host_node_menu(Host, Node, Lang,
 				       JID, Level),
@@ -1897,7 +1897,6 @@ make_navigation_menu(Host, Node, Lang, JID, Level) ->
     NodeMenu = make_node_menu(Host, Node, Lang, Level),
     make_server_menu(HostMenu, NodeMenu, Lang, JID, Level).
 
-%% @spec (Host, Node, Base, Lang) -> [LI]
 make_menu_items(global, cluster, Base, Lang) ->
     HookItems = get_menu_items_hook(server, Lang),
     make_menu_items(Lang, {Base, <<"">>, HookItems});
@@ -1978,9 +1977,11 @@ get_menu_items_hook({node, Node}, Lang) ->
 get_menu_items_hook(server, Lang) ->
     ejabberd_hooks:run_fold(webadmin_menu_main, [], [Lang]).
 
-%% @spec (Lang::string(), Menu) -> [LI]
-%% where Menu = {MURI::string(), MName::string(), Items::[Item]}
-%%       Item = {IURI::string(), IName::string()} | {IURI::string(), IName::string(), Menu}
+-spec make_menu_items(Lang::binary(),
+                      {MURI::binary(), MName::binary(),
+                       Items::[{IURI::binary(), IName::binary()}
+                               | {IURI::binary(), IName::binary(), Menu::any()}]}) ->
+    [xmlel()].
 make_menu_items(Lang, Menu) ->
     lists:reverse(make_menu_items2(Lang, 1, Menu)).
 

src/mod_admin_extra.erl

@@ -1538,7 +1538,8 @@ srg_user_del(User, Host, Group, GroupHost) ->
 %%%
 
 %% @doc Send a message to an XMPP account.
-%% @spec (Type::binary(), From::binary(), To::binary(), Subject::binary(), Body::binary()) -> ok
+-spec send_message(Type::binary(), From::binary(), To::binary(),
+                   Subject::binary(), Body::binary()) -> ok.
 send_message(Type, From, To, Subject, Body) ->
     CodecOpts = ejabberd_config:codec_options(),
     try xmpp:decode(

src/mod_http_fileserver.erl

@@ -151,7 +151,9 @@ initialize(Host, Opts) ->
 	   content_types = ContentTypes,
 	   user_access = UserAccess}.
 
-%% @spec (AdminCTs::[CT], Default::[CT]) -> [CT]
+-spec build_list_content_types(AdminCTs::[{binary(), binary()|undefined}],
+                               Default::[{binary(), binary()|undefined}]) ->
+    [{string(), string()|undefined}].
 %% where CT = {Extension::string(), Value}
 %%       Value = string() | undefined
 %% @doc Return a unified list without duplicates.
@@ -265,7 +267,8 @@ code_change(_OldVsn, State, _Extra) ->
 %% request_handlers callbacks
 %%====================================================================
 
-%% @spec (LocalPath, Request) -> {HTTPCode::integer(), [Header], Page::string()}
+-spec process(LocalPath::[binary()], #request{}) ->
+    {HTTPCode::integer(), [{binary(), binary()}], Page::string()}.
 %% @doc Handle an HTTP request.
 %% LocalPath is the part of the requested URL path that is "local to the module".
 %% Returns the page to be sent back to the client and/or HTTP status code.

src/mod_mqtt_session.erl

@@ -436,7 +436,7 @@ upgrade_state(State) ->
 	    upgrade_state(setelement(2, State1, VSN+1))
     end.
 
--spec upgrade_state(tuple(), 1..?VSN) -> tuple().
+-spec upgrade_state(tuple(), integer()) -> tuple().
 upgrade_state(OldState, 1) ->
     %% Appending 'tls' field
     erlang:append_element(OldState, false);

src/mod_muc_admin.erl

@@ -695,8 +695,7 @@ justcreated_to_binary(J) when is_atom(J) ->
 %% Create/Delete Room
 %%----------------------------
 
-%% @spec (Name::binary(), Host::binary(), ServerHost::binary()) ->
-%%       ok | error
+-spec create_room(Name::binary(), Host::binary(), ServerHost::binary()) -> ok | error.
 %% @doc Create a room immediately with the default options.
 create_room(Name1, Host1, ServerHost) ->
     create_room_with_opts(Name1, Host1, ServerHost, []).
@@ -747,8 +746,7 @@ muc_create_room(ServerHost, {Name, Host, _}, DefRoomOpts) ->
     io:format("Creating room ~ts@~ts~n", [Name, Host]),
     mod_muc:store_room(ServerHost, Host, Name, DefRoomOpts).
 
-%% @spec (Name::binary(), Host::binary()) ->
-%%       ok | {error, room_not_exists}
+-spec destroy_room(Name::binary(), Host::binary()) -> ok | {error, room_not_exists}.
 %% @doc Destroy the room immediately.
 %% If the room has participants, they are not notified that the room was destroyed;
 %% they will notice when they try to chat and receive an error that the room doesn't exist.
@@ -1116,8 +1114,8 @@ send_direct_invitation(FromJid, UserJid, Msg) ->
 %% Change Room Option
 %%----------------------------
 
-%% @spec(Name::string(), Service::string(), Option::string(), Value) -> ok
-%%       Value = atom() | integer() | string()
+-spec change_room_option(Name::binary(), Service::binary(), Option::binary(),
+                         Value::atom() | integer() | string()) -> ok | mod_muc_log_not_enabled.
 %% @doc Change an option in an existing room.
 %% Requires the name of the room, the MUC service where it exists,
 %% the option to change (for example title or max_users),

src/mod_pubsub.erl

@@ -3414,11 +3414,6 @@ node_config(Node, ServerHost, [{RE, Opts}|NodeOpts]) ->
 node_config(_, _, []) ->
     [].
 
-%% @spec (Host, Options) -> MaxItems
-%%         Host = host()
-%%         Options = [Option]
-%%         Option = {Key::atom(), Value::term()}
-%%         MaxItems = integer() | unlimited
 %% @doc <p>Return the maximum number of items for a given node.</p>
 %% <p>Unlimited means that there is no limit in the number of items that can
 %% be stored.</p>

src/mod_roster_mnesia.erl

@@ -194,7 +194,6 @@ process_rosteritems(ActionS, SubsS, AsksS, UsersS, ContactsS) ->
                 ),
     rosteritem_purge({Action, Subs, Asks, Users, Contacts}).
 
-%% @spec ({Action::atom(), Subs::[atom()], Asks::[atom()], User::string(), Contact::string()}) -> {atomic, ok}
 rosteritem_purge(Options) ->
     Num_rosteritems = mnesia:table_info(roster, size),
     io:format("There are ~p roster items in total.~n", [Num_rosteritems]),

src/mod_shared_roster.erl

@@ -512,7 +512,8 @@ get_group_opt_cached(Host, Group, Opt, Default, Cache) ->
 	    proplists:get_value(Opt, Opts, Default)
     end.
 
-%% @spec (Host::string(), Group::string(), Opt::atom(), Default) -> OptValue | Default
+-spec get_group_opt(Host::binary(), Group::binary(), displayed_groups | label, Default) ->
+    OptValue::any() | Default.
 get_group_opt(Host, Group, Opt, Default) ->
     case get_group_opts(Host, Group) of
       error -> Default;
@@ -687,7 +688,8 @@ is_user_in_group(US, Group, Host) ->
 	    true
     end.
 
-%% @spec (Host::string(), {User::string(), Server::string()}, Group::string()) -> {atomic, ok} | error
+-spec add_user_to_group(Host::binary(), {User::binary(), Server::binary()},
+                        Group::binary()) -> {atomic, ok} | error.
 add_user_to_group(Host, US, Group) ->
     {_LUser, LServer} = US,
     case lists:member(LServer, ejabberd_config:get_option(hosts)) of