Describe even more command arguments and results in mod_admin_extra

src/mod_admin_extra.erl

@@ -303,6 +303,9 @@ get_commands_spec() ->
 			desc = "List of users logged in host with their statuses",
 			module = ?MODULE, function = status_list,
 			args = [{host, binary}, {status, binary}],
+			args_example = [<<"myserver.com">>, <<"dnd">>],
+			args_desc = ["Server name", "Status type to check"],
+			result_example = [{<<"peter">>,<<"myserver.com">>,<<"tka">>,6,<<"Busy">>}],
 			result = {users, {list,
 					  {userstatus, {tuple, [
 								{user, string},
@@ -316,6 +319,9 @@ get_commands_spec() ->
 			desc = "List of logged users with this status",
 			module = ?MODULE, function = status_list,
 			args = [{status, binary}],
+			args_example = [<<"dnd">>],
+			args_desc = ["Status type to check"],
+			result_example = [{<<"peter">>,<<"myserver.com">>,<<"tka">>,6,<<"Busy">>}],
 			result = {users, {list,
 					  {userstatus, {tuple, [
 								{user, string},
@@ -330,6 +336,8 @@ get_commands_spec() ->
 			desc = "List all established sessions and their information",
 			module = ?MODULE, function = connected_users_info,
 			args = [],
+			result_example = [{"user1@myserver.com/tka", "c2s", "127.0.0.1",
+                                           40092, 8, "ejabberd@localhost", 28}],
 			result = {connected_users_info,
 				  {list,
 				   {sessions, {tuple,
@@ -346,6 +354,9 @@ get_commands_spec() ->
 			tags = [session],
 			desc = "Get the list of established sessions in a vhost",
 			module = ?MODULE, function = connected_users_vhost,
+			args_example = [<<"myexample.com">>],
+			args_desc = ["Server name"],
+			result_example = [<<"user1@myserver.com/tka">>, <<"user2@localhost/tka">>],
 			args = [{host, binary}],
 			result = {connected_users_vhost, {list, {sessions, string}}}},
      #ejabberd_commands{name = user_sessions_info,
@@ -353,6 +364,10 @@ get_commands_spec() ->
 			desc = "Get information about all sessions of a user",
 			module = ?MODULE, function = user_sessions_info,
 			args = [{user, binary}, {host, binary}],
+			args_example = [<<"peter">>, <<"myserver.com">>],
+			args_desc = ["User name", "Server name"],
+			result_example = [{"c2s", "127.0.0.1", 42656,8, "ejabberd@localhost",
+                                           231, <<"dnd">>, <<"tka">>, <<>>}],
 			result = {sessions_info,
 				  {list,
 				   {session, {tuple,
@@ -385,6 +400,9 @@ get_commands_spec() ->
 			    "defined by the user client.",
 			module = ?MODULE, function = get_presence,
 			args = [{user, binary}, {server, binary}],
+			args_example = [<<"peter">>, <<"myexample.com">>],
+			args_desc = ["User name", "Server name"],
+			result_example = {<<"user1@myserver.com/tka">>, <<"dnd">>, <<"Busy">>},
 			result =
 			    {presence,
 			     {tuple,
@@ -398,24 +416,40 @@ get_commands_spec() ->
 				{resource, binary}, {type, binary},
 				{show, binary}, {status, binary},
 				{priority, binary}],
+			args_example = [<<"user1">>,<<"myserver.com">>,<<"tka1">>,
+					<<"available">>,<<"away">>,<<"BB">>, <<"7">>],
+			args_desc = ["User name", "Server name", "Resource",
+					"Type: available, error, probe...",
+					"Show: away, chat, dnd, xa.", "Status text",
+					"Priority, provide this value as an integer"],
 			result = {res, rescode}},
 
      #ejabberd_commands{name = set_nickname, tags = [vcard],
 			desc = "Set nickname in a user's vCard",
 			module = ?MODULE, function = set_nickname,
 			args = [{user, binary}, {host, binary}, {nickname, binary}],
+			args_example = [<<"user1">>,<<"myserver.com">>,<<"User 1">>],
+			args_desc = ["User name", "Server name", "Nickname"],
 			result = {res, rescode}},
      #ejabberd_commands{name = get_vcard, tags = [vcard],
 			desc = "Get content from a vCard field",
 			longdesc = Vcard1FieldsString ++ "\n" ++ Vcard2FieldsString ++ "\n\n" ++ VcardXEP,
 			module = ?MODULE, function = get_vcard,
 			args = [{user, binary}, {host, binary}, {name, binary}],
+			args_example = [<<"user1">>,<<"myserver.com">>,<<"NICKNAME">>],
+			args_desc = ["User name", "Server name", "Field name"],
+			result_example = "User 1",
+			result_desc = "Field content",
 			result = {content, string}},
      #ejabberd_commands{name = get_vcard2, tags = [vcard],
-			desc = "Get content from a vCard field",
+			desc = "Get content from a vCard subfield",
 			longdesc = Vcard2FieldsString ++ "\n\n" ++ Vcard1FieldsString ++ "\n" ++ VcardXEP,
 			module = ?MODULE, function = get_vcard,
 			args = [{user, binary}, {host, binary}, {name, binary}, {subname, binary}],
+			args_example = [<<"user1">>,<<"myserver.com">>,<<"N">>, <<"FAMILY">>],
+			args_desc = ["User name", "Server name", "Field name", "Subfield name"],
+			result_example = "Schubert",
+			result_desc = "Field content",
 			result = {content, string}},
      #ejabberd_commands{name = get_vcard2_multi, tags = [vcard],
 			desc = "Get multiple contents from a vCard field",
@@ -429,12 +463,16 @@ get_commands_spec() ->
 			longdesc = Vcard1FieldsString ++ "\n" ++ Vcard2FieldsString ++ "\n\n" ++ VcardXEP,
 			module = ?MODULE, function = set_vcard,
 			args = [{user, binary}, {host, binary}, {name, binary}, {content, binary}],
+			args_example = [<<"user1">>,<<"myserver.com">>, <<"URL">>, <<"www.example.com">>],
+			args_desc = ["User name", "Server name", "Field name", "Value"],
 			result = {res, rescode}},
      #ejabberd_commands{name = set_vcard2, tags = [vcard],
 			desc = "Set content in a vCard subfield",
 			longdesc = Vcard2FieldsString ++ "\n\n" ++ Vcard1FieldsString ++ "\n" ++ VcardXEP,
 			module = ?MODULE, function = set_vcard,
 			args = [{user, binary}, {host, binary}, {name, binary}, {subname, binary}, {content, binary}],
+			args_example = [<<"user1">>,<<"myserver.com">>,<<"TEL">>, <<"NUMBER">>, <<"123456">>],
+			args_desc = ["User name", "Server name", "Field name", "Subfield name", "Value"],
 			result = {res, rescode}},
      #ejabberd_commands{name = set_vcard2_multi, tags = [vcard],
 			desc = "Set multiple contents in a vCard subfield",
@@ -451,6 +489,10 @@ get_commands_spec() ->
 				{user, binary}, {server, binary},
 				{nick, binary}, {group, binary},
 				{subs, binary}],
+			args_example = [<<"user1">>,<<"myserver.com">>,<<"user2">>, <<"myserver.com">>,
+				<<"User 2">>, <<"Friends">>, <<"both">>],
+			args_desc = ["User name", "Server name", "Contact user name", "Contact server name",
+				"Nickname", "Group", "Subscription"],
 			result = {res, rescode}},
      %%{"", "subs= none, from, to or both"},
      %%{"", "example: add-roster peter localhost mike server.com MiKe Employees both"},
@@ -460,6 +502,8 @@ get_commands_spec() ->
 			module = ?MODULE, function = delete_rosteritem,
 			args = [{localuser, binary}, {localserver, binary},
 				{user, binary}, {server, binary}],
+			args_example = [<<"user1">>,<<"myserver.com">>,<<"user2">>, <<"myserver.com">>],
+			args_desc = ["User name", "Server name", "Contact user name", "Contact server name"],
 			result = {res, rescode}},
      #ejabberd_commands{name = process_rosteritems, tags = [roster],
 			desc = "List/delete rosteritems that match filter (only Mnesia)",
@@ -514,8 +558,14 @@ get_commands_spec() ->
 								     ]}}}}},
      #ejabberd_commands{name = push_roster, tags = [roster],
 			desc = "Push template roster from file to a user",
+			longdesc = "The text file must contain an erlang term: a list "
+			    "of tuples with username, servername, group and nick. Example:\n"
+			    "[{\"user1\", \"localhost\", \"Workers\", \"User 1\"},\n"
+			    " {\"user2\", \"localhost\", \"Workers\", \"User 2\"}].",
 			module = ?MODULE, function = push_roster,
 			args = [{file, binary}, {user, binary}, {host, binary}],
+			args_example = [<<"/home/ejabberd/roster.txt">>, <<"user1">>, <<"localhost">>],
+			args_desc = ["File path", "User name", "Server name"],
 			result = {res, rescode}},
      #ejabberd_commands{name = push_roster_all, tags = [roster],
 			desc = "Push template roster from file to all those users",
@@ -525,11 +575,15 @@ get_commands_spec() ->
 			    " {\"user2\", \"localhost\", \"Workers\", \"User 2\"}].",
 			module = ?MODULE, function = push_roster_all,
 			args = [{file, binary}],
+			args_example = [<<"/home/ejabberd/roster.txt">>],
+			args_desc = ["File path"],
 			result = {res, rescode}},
      #ejabberd_commands{name = push_alltoall, tags = [roster],
 			desc = "Add all the users to all the users of Host in Group",
 			module = ?MODULE, function = push_alltoall,
 			args = [{host, binary}, {group, binary}],
+			args_example = [<<"myserver.com">>,<<"Everybody">>],
+			args_desc = ["Server name", "Group name"],
 			result = {res, rescode}},
 
      #ejabberd_commands{name = get_last, tags = [last],
@@ -538,6 +592,10 @@ get_commands_spec() ->
 			    "2017-02-23T22:25:28.063062Z     ONLINE",
 			module = ?MODULE, function = get_last,
 			args = [{user, binary}, {host, binary}],
+			args_example = [<<"user1">>,<<"myserver.com">>],
+			args_desc = ["User name", "Server name"],
+			result_example = {<<"2017-06-30T14:32:16.060684Z">>, "ONLINE"},
+			result_desc = "Last activity timestamp and status",
 			result = {last_activity,
 				  {tuple, [{timestamp, string},
 					   {status, string}
@@ -548,17 +606,24 @@ get_commands_spec() ->
 			"1970-01-01 00:00:00 UTC, for example: date +%s",
 			module = mod_last, function = store_last_info,
 			args = [{user, binary}, {host, binary}, {timestamp, integer}, {status, binary}],
+			args_example = [<<"user1">>,<<"myserver.com">>, <<"2017-06-30T14:32:16.060684Z">>, <<"GoSleeping">>],
+			args_desc = ["User name", "Server name"],
 			result = {res, rescode}},
 
      #ejabberd_commands{name = private_get, tags = [private],
 			desc = "Get some information from a user private storage",
 			module = ?MODULE, function = private_get,
 			args = [{user, binary}, {host, binary}, {element, binary}, {ns, binary}],
+			args_example = [<<"user1">>,<<"myserver.com">>,<<"storage">>, <<"storage:rosternotes">>],
+			args_desc = ["User name", "Server name", "Element name", "Namespace"],
 			result = {res, string}},
      #ejabberd_commands{name = private_set, tags = [private],
 			desc = "Set to the user private storage",
 			module = ?MODULE, function = private_set,
 			args = [{user, binary}, {host, binary}, {element, binary}],
+			args_example = [<<"user1">>,<<"myserver.com">>,
+                            <<"<query xmlns='jabber:iq:private'> <storage xmlns='storage:rosternotes'/></query>">>],
+			args_desc = ["User name", "Server name", "XML storage element"],
 			result = {res, rescode}},
 
      #ejabberd_commands{name = srg_create, tags = [shared_roster_group],
@@ -568,41 +633,63 @@ get_commands_spec() ->
 			"put  \\ \" around the argument and\nseparate the "
 			"identifiers with \\ \\ n\n"
 			"For example:\n"
-			"  ejabberdctl srg_create group3 localhost "
+			"  ejabberdctl srg_create group3 myserver.com "
 			"name desc \\\"group1\\\\ngroup2\\\"",
 			module = ?MODULE, function = srg_create,
 			args = [{group, binary}, {host, binary},
 				{name, binary}, {description, binary}, {display, binary}],
+			args_example = [<<"group3">>, <<"myserver.com">>, <<"Group3">>,
+				<<"Third group">>, <<"group1\\\\ngroup2">>],
+			args_desc = ["Group identifier", "Group server name", "Group name",
+				"Group description", "Groups to display"],
 			result = {res, rescode}},
      #ejabberd_commands{name = srg_delete, tags = [shared_roster_group],
 			desc = "Delete a Shared Roster Group",
 			module = ?MODULE, function = srg_delete,
 			args = [{group, binary}, {host, binary}],
+			args_example = [<<"group3">>, <<"myserver.com">>],
+			args_desc = ["Group identifier", "Group server name"],
 			result = {res, rescode}},
      #ejabberd_commands{name = srg_list, tags = [shared_roster_group],
 			desc = "List the Shared Roster Groups in Host",
 			module = ?MODULE, function = srg_list,
 			args = [{host, binary}],
+			args_example = [<<"myserver.com">>],
+			args_desc = ["Server name"],
+			result_example = [<<"group1">>, <<"group2">>],
+			result_desc = "List of group identifiers",
 			result = {groups, {list, {id, string}}}},
      #ejabberd_commands{name = srg_get_info, tags = [shared_roster_group],
 			desc = "Get info of a Shared Roster Group",
 			module = ?MODULE, function = srg_get_info,
 			args = [{group, binary}, {host, binary}],
+			args_example = [<<"group3">>, <<"myserver.com">>],
+			args_desc = ["Group identifier", "Group server name"],
+			result_example = [{<<"name">>, "Group 3"}, {<<"displayed_groups">>, "group1"}],
+			result_desc = "List of group informations, as key and value",
 			result = {informations, {list, {information, {tuple, [{key, string}, {value, string}]}}}}},
      #ejabberd_commands{name = srg_get_members, tags = [shared_roster_group],
 			desc = "Get members of a Shared Roster Group",
 			module = ?MODULE, function = srg_get_members,
 			args = [{group, binary}, {host, binary}],
+			args_example = [<<"group3">>, <<"myserver.com">>],
+			args_desc = ["Group identifier", "Group server name"],
+			result_example = [<<"user1@localhost">>, <<"user2@localhost">>],
+			result_desc = "List of group identifiers",
 			result = {members, {list, {member, string}}}},
      #ejabberd_commands{name = srg_user_add, tags = [shared_roster_group],
 			desc = "Add the JID user@host to the Shared Roster Group",
 			module = ?MODULE, function = srg_user_add,
 			args = [{user, binary}, {host, binary}, {group, binary}, {grouphost, binary}],
+			args_example = [<<"user1">>, <<"myserver.com">>, <<"group3">>, <<"myserver.com">>],
+			args_desc = ["Username", "User server name", "Group identifier", "Group server name"],
 			result = {res, rescode}},
      #ejabberd_commands{name = srg_user_del, tags = [shared_roster_group],
 			desc = "Delete this JID user@host from the Shared Roster Group",
 			module = ?MODULE, function = srg_user_del,
 			args = [{user, binary}, {host, binary}, {group, binary}, {grouphost, binary}],
+			args_example = [<<"user1">>, <<"myserver.com">>, <<"group3">>, <<"myserver.com">>],
+			args_desc = ["Username", "User server name", "Group identifier", "Group server name"],
 			result = {res, rescode}},
 
      #ejabberd_commands{name = get_offline_count,
@@ -611,27 +698,42 @@ get_commands_spec() ->
 			policy = user,
 			module = mod_offline, function = count_offline_messages,
 			args = [],
+			result_example = 5,
+			result_desc = "Number",
 			result = {value, integer}},
      #ejabberd_commands{name = send_message, tags = [stanza],
 			desc = "Send a message to a local or remote bare of full JID",
 			module = ?MODULE, function = send_message,
 			args = [{type, binary}, {from, binary}, {to, binary},
 				{subject, binary}, {body, binary}],
+			args_example = [<<"headline">>, <<"admin@localhost">>, <<"user1@localhost">>,
+				<<"Restart">>, <<"In 5 minutes">>],
+			args_desc = ["Message type: normal, chat, headline", "User server name",
+				"Sender JID", "Destination JID", "Subject, or empty string", "Body"],
 			result = {res, rescode}},
      #ejabberd_commands{name = send_stanza_c2s, tags = [stanza],
 			desc = "Send a stanza as if sent from a c2s session",
 			module = ?MODULE, function = send_stanza_c2s,
 			args = [{user, binary}, {host, binary}, {resource, binary}, {stanza, binary}],
+			args_example = [<<"admin">>, <<"myserver.com">>, <<"bot">>,
+				<<"<message to='user1@localhost'><ext attr='value'/></message>">>],
+			args_desc = ["Username", "Server name", "Resource", "Stanza"],
 			result = {res, rescode}},
      #ejabberd_commands{name = send_stanza, tags = [stanza],
 			desc = "Send a stanza; provide From JID and valid To JID",
 			module = ?MODULE, function = send_stanza,
 			args = [{from, binary}, {to, binary}, {stanza, binary}],
+			args_example = [<<"admin@localhost">>, <<"user1@localhost">>,
+				<<"<message><ext attr='value'/></message>">>],
+			args_desc = ["Sender JID", "Destination JID", "Stanza"],
 			result = {res, rescode}},
      #ejabberd_commands{name = privacy_set, tags = [stanza],
 			desc = "Send a IQ set privacy stanza for a local account",
 			module = ?MODULE, function = privacy_set,
 			args = [{user, binary}, {host, binary}, {xmlquery, binary}],
+			args_example = [<<"user1">>, <<"myserver.com">>,
+				<<"<query xmlns='jabber:iq:privacy'>...">>],
+			args_desc = ["Username", "Server name", "Query XML element"],
 			result = {res, rescode}},
 
      #ejabberd_commands{name = stats, tags = [stats],
@@ -639,12 +741,20 @@ get_commands_spec() ->
 			policy = admin,
 			module = ?MODULE, function = stats,
 			args = [{name, binary}],
+			args_example = [<<"registeredusers">>],
+			args_desc = ["Statistic name"],
+			result_example = 6,
+			result_desc = "Integer statistic value",
 			result = {stat, integer}},
      #ejabberd_commands{name = stats_host, tags = [stats],
 			desc = "Get statistical value for this host: registeredusers onlineusers",
 			policy = admin,
 			module = ?MODULE, function = stats,
 			args = [{name, binary}, {host, binary}],
+			args_example = [<<"registeredusers">>, <<"example.com">>],
+			args_desc = ["Statistic name"],
+			result_example = 6,
+			result_desc = "Integer statistic value",
 			result = {stat, integer}}
     ].
 
@@ -952,7 +1062,7 @@ connected_users_info() ->
 
 connected_users_vhost(Host) ->
     USRs = ejabberd_sm:get_vh_session_list(Host),
-    [ [U, $@, S, $/, R] || {U, S, R} <- USRs].
+    [ jid:encode(jid:make(USR)) || USR <- USRs].
 
 %% Code copied from ejabberd_sm.erl and customized
 dirty_get_sessions_list2() ->