Chapril/xmpp.chapril.org-ejabberd
25
1
Fork 0
mirror of https://github.com/processone/ejabberd.git synced 2024-11-24 16:23:40 +01:00
Code Releases Activity

Commands: Improve syntax of many commands documentation

Browse Source
This commit is contained in:
Badlop 2023-11-24 11:58:50 +01:00
parent 0961fa1830
commit c5a5dd859e
5 changed files with 86 additions and 72 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
src/ejabberd_acme.erl
View File

@ -450,11 +450,11 @@ delete_obsolete_data() ->
%%%=================================================================== %%%===================================================================
get_commands_spec() -> get_commands_spec() ->
[#ejabberd_commands{name = request_certificate, tags = [acme], [#ejabberd_commands{name = request_certificate, tags = [acme],
desc = "Requests certificates for all or the specified " desc = "Requests certificates for all or some domains",
"domains: all | domain1,domain2,...", longdesc = "Domains can be `all`, or a list of domains separared with comma characters",
module = ?MODULE, function = request_certificate, module = ?MODULE, function = request_certificate,
args_desc = ["Domains for which to acquire a certificate"], args_desc = ["Domains for which to acquire a certificate"],
args_example = ["all | domain.tld,conference.domain.tld,..."], args_example = ["example.com,domain.tld,conference.domain.tld"],
args = [{domains, string}], args = [{domains, string}],
result = {res, restuple}}, result = {res, restuple}},
#ejabberd_commands{name = list_certificates, tags = [acme], #ejabberd_commands{name = list_certificates, tags = [acme],

12
src/ejabberd_admin.erl
View File

@ -129,7 +129,7 @@ get_commands_spec() ->
desc = "Reopen the log files after being renamed", desc = "Reopen the log files after being renamed",
longdesc = "This can be useful when an external tool is " longdesc = "This can be useful when an external tool is "
"used for log rotation. See " "used for log rotation. See "
"https://docs.ejabberd.im/admin/guide/troubleshooting/#log-files", "[Log Files](https://docs.ejabberd.im/admin/guide/troubleshooting/#log-files).",
policy = admin, policy = admin,
module = ?MODULE, function = reopen_log, module = ?MODULE, function = reopen_log,
args = [], result = {res, rescode}}, args = [], result = {res, rescode}},
@ -157,9 +157,10 @@ get_commands_spec() ->
result = {levelatom, atom}}, result = {levelatom, atom}},
#ejabberd_commands{name = set_loglevel, tags = [logs], #ejabberd_commands{name = set_loglevel, tags = [logs],
desc = "Set the loglevel", desc = "Set the loglevel",
longdesc = "Possible loglevels: `none`, `emergency`, `alert`, `critical`,
`error`, `warning`, `notice`, `info`, `debug`.",
module = ?MODULE, function = set_loglevel, module = ?MODULE, function = set_loglevel,
args_desc = ["Desired logging level: none | emergency | alert | critical " args_desc = ["Desired logging level"],
"| error | warning | notice | info | debug"],
args_example = ["debug"], args_example = ["debug"],
args = [{loglevel, string}], args = [{loglevel, string}],
result = {res, rescode}}, result = {res, rescode}},
@ -171,7 +172,8 @@ get_commands_spec() ->
result_example = ["mod_configure", "mod_vcard"], result_example = ["mod_configure", "mod_vcard"],
result = {modules, {list, {module, string}}}}, result = {modules, {list, {module, string}}}},
#ejabberd_commands{name = update, tags = [server], #ejabberd_commands{name = update, tags = [server],
desc = "Update the given module, or use the keyword: all", desc = "Update the given module",
longdesc = "To update all the possible modules, use `all`.",
module = ?MODULE, function = update, module = ?MODULE, function = update,
args_example = ["mod_vcard"], args_example = ["mod_vcard"],
args = [{module, string}], args = [{module, string}],
@ -373,7 +375,7 @@ get_commands_spec() ->
result = {res, rescode}}, result = {res, rescode}},
#ejabberd_commands{name = set_master, tags = [cluster], #ejabberd_commands{name = set_master, tags = [cluster],
desc = "Set master node of the clustered Mnesia tables", desc = "Set master node of the clustered Mnesia tables",
longdesc = "If you provide as nodename `self`, this " longdesc = "If `nodename` is set to `self`, then this "
"node will be set as its own master.", "node will be set as its own master.",
module = ?MODULE, function = set_master, module = ?MODULE, function = set_master,
args_desc = ["Name of the erlang node that will be considered master of this node"], args_desc = ["Name of the erlang node that will be considered master of this node"],

14
src/ejabberd_oauth.erl
View File

@ -81,7 +81,7 @@
get_commands_spec() -> get_commands_spec() ->
[ [
#ejabberd_commands{name = oauth_issue_token, tags = [oauth], #ejabberd_commands{name = oauth_issue_token, tags = [oauth],
desc = "Issue an oauth token for the given jid", desc = "Issue an [OAuth](https://docs.ejabberd.im/developer/ejabberd-api/oauth/) token for the given jid",
module = ?MODULE, function = oauth_issue_token, module = ?MODULE, function = oauth_issue_token,
args = [{jid, string},{ttl, integer}, {scopes, string}], args = [{jid, string},{ttl, integer}, {scopes, string}],
policy = restricted, policy = restricted,
@ -92,15 +92,15 @@ get_commands_spec() ->
result = {result, {tuple, [{token, string}, {scopes, string}, {expires_in, string}]}} result = {result, {tuple, [{token, string}, {scopes, string}, {expires_in, string}]}}
}, },
#ejabberd_commands{name = oauth_list_tokens, tags = [oauth], #ejabberd_commands{name = oauth_list_tokens, tags = [oauth],
desc = "List oauth tokens, user, scope, and seconds to expire (only Mnesia)", desc = "List [OAuth](https://docs.ejabberd.im/developer/ejabberd-api/oauth/) tokens, user, scope, and seconds to expire (only Mnesia)",
longdesc = "List oauth tokens, their user and scope, and how many seconds remain until expirity", longdesc = "List OAuth tokens, their user and scope, and how many seconds remain until expirity",
module = ?MODULE, function = oauth_list_tokens, module = ?MODULE, function = oauth_list_tokens,
args = [], args = [],
policy = restricted, policy = restricted,
result = {tokens, {list, {token, {tuple, [{token, string}, {user, string}, {scope, string}, {expires_in, string}]}}}} result = {tokens, {list, {token, {tuple, [{token, string}, {user, string}, {scope, string}, {expires_in, string}]}}}}
}, },
#ejabberd_commands{name = oauth_revoke_token, tags = [oauth], #ejabberd_commands{name = oauth_revoke_token, tags = [oauth],
desc = "Revoke authorization for a token", desc = "Revoke authorization for an [OAuth](https://docs.ejabberd.im/developer/ejabberd-api/oauth/) token",
note = "changed in 22.05", note = "changed in 22.05",
module = ?MODULE, function = oauth_revoke_token, module = ?MODULE, function = oauth_revoke_token,
args = [{token, binary}], args = [{token, binary}],
@ -109,7 +109,7 @@ get_commands_spec() ->
result_desc = "Result code" result_desc = "Result code"
}, },
#ejabberd_commands{name = oauth_add_client_password, tags = [oauth], #ejabberd_commands{name = oauth_add_client_password, tags = [oauth],
desc = "Add OAUTH client_id with password grant type", desc = "Add [OAuth](https://docs.ejabberd.im/developer/ejabberd-api/oauth/) client_id with password grant type",
module = ?MODULE, function = oauth_add_client_password, module = ?MODULE, function = oauth_add_client_password,
args = [{client_id, binary}, args = [{client_id, binary},
{client_name, binary}, {client_name, binary},
@ -118,7 +118,7 @@ get_commands_spec() ->
result = {res, restuple} result = {res, restuple}
}, },
#ejabberd_commands{name = oauth_add_client_implicit, tags = [oauth], #ejabberd_commands{name = oauth_add_client_implicit, tags = [oauth],
desc = "Add OAUTH client_id with implicit grant type", desc = "Add [OAuth](https://docs.ejabberd.im/developer/ejabberd-api/oauth/) client_id with implicit grant type",
module = ?MODULE, function = oauth_add_client_implicit, module = ?MODULE, function = oauth_add_client_implicit,
args = [{client_id, binary}, args = [{client_id, binary},
{client_name, binary}, {client_name, binary},
@ -127,7 +127,7 @@ get_commands_spec() ->
result = {res, restuple} result = {res, restuple}
}, },
#ejabberd_commands{name = oauth_remove_client, tags = [oauth], #ejabberd_commands{name = oauth_remove_client, tags = [oauth],
desc = "Remove OAUTH client_id", desc = "Remove [OAuth](https://docs.ejabberd.im/developer/ejabberd-api/oauth/) client_id",
module = ?MODULE, function = oauth_remove_client, module = ?MODULE, function = oauth_remove_client,
args = [{client_id, binary}], args = [{client_id, binary}],
policy = restricted, policy = restricted,

116
src/mod_admin_extra.erl
View File

@ -113,14 +113,14 @@ depends(_Host, _Opts) ->
%%% %%%
get_commands_spec() -> get_commands_spec() ->
Vcard1FieldsString = "Some vcard field names in get/set_vcard are:\n\n" Vcard1FieldsString = "Some vcard field names in `get`/`set_vcard` are:\n\n"
"* FN - Full Name\n" "* FN - Full Name\n"
"* NICKNAME - Nickname\n" "* NICKNAME - Nickname\n"
"* BDAY - Birthday\n" "* BDAY - Birthday\n"
"* TITLE - Work: Position\n" "* TITLE - Work: Position\n"
"* ROLE - Work: Role\n", "* ROLE - Work: Role\n",
Vcard2FieldsString = "Some vcard field names and subnames in get/set_vcard2 are:\n\n" Vcard2FieldsString = "Some vcard field names and subnames in `get`/`set_vcard2` are:\n\n"
"* N FAMILY - Family name\n" "* N FAMILY - Family name\n"
"* N GIVEN - Given name\n" "* N GIVEN - Given name\n"
"* N MIDDLE - Middle name\n" "* N MIDDLE - Middle name\n"
@ -134,8 +134,8 @@ get_commands_spec() ->
"* ORG ORGNAME - Work: Company\n" "* ORG ORGNAME - Work: Company\n"
"* ORG ORGUNIT - Work: Department\n", "* ORG ORGUNIT - Work: Department\n",
VcardXEP = "For a full list of vCard fields check XEP-0054: vcard-temp at " VcardXEP = "For a full list of vCard fields check [XEP-0054: vcard-temp]"
"https://xmpp.org/extensions/xep-0054.html", "(https://xmpp.org/extensions/xep-0054.html)",
[ [
#ejabberd_commands{name = compile, tags = [erlang], #ejabberd_commands{name = compile, tags = [erlang],
@ -162,9 +162,9 @@ get_commands_spec() ->
result = {res, integer}, result = {res, integer},
result_example = 0, result_example = 0,
result_desc = "Returns integer code:\n" result_desc = "Returns integer code:\n"
" - 0: code reloaded, module restarted\n" " - `0`: code reloaded, module restarted\n"
" - 1: error: module not loaded\n" " - `1`: error: module not loaded\n"
" - 2: code not reloaded, but module restarted"}, " - `2`: code not reloaded, but module restarted"},
#ejabberd_commands{name = delete_old_users, tags = [accounts, purge], #ejabberd_commands{name = delete_old_users, tags = [accounts, purge],
desc = "Delete users that didn't log in last days, or that never logged", desc = "Delete users that didn't log in last days, or that never logged",
longdesc = "To protect admin accounts, configure this for example:\n" longdesc = "To protect admin accounts, configure this for example:\n"
@ -509,52 +509,56 @@ get_commands_spec() ->
result = {res, rescode}}, result = {res, rescode}},
#ejabberd_commands{name = process_rosteritems, tags = [roster], #ejabberd_commands{name = process_rosteritems, tags = [roster],
desc = "List/delete rosteritems that match filter", desc = "List/delete rosteritems that match filter",
longdesc = "Explanation of each argument:\n" longdesc = "Explanation of each argument:\n\n"
" - action: what to do with each rosteritem that " "* `action`: what to do with each rosteritem that "
"matches all the filtering options\n" "matches all the filtering options\n"
" - subs: subscription type\n" "* `subs`: subscription type\n"
" - asks: pending subscription\n" "* `asks`: pending subscription\n"
" - users: the JIDs of the local user\n" "* `users`: the JIDs of the local user\n"
" - contacts: the JIDs of the contact in the roster\n" "* `contacts`: the JIDs of the contact in the roster\n"
"\n" "\n"
" *** Mnesia: \n" "**Mnesia backend:**\n"
"\n" "\n"
"Allowed values in the arguments:\n" "Allowed values in the arguments:\n\n"
" ACTION = list | delete\n" "* `action` = `list` | `delete`\n"
" SUBS = SUB[:SUB]* | any\n" "* `subs` = `any` | SUB[:SUB]*\n"
" SUB = none | from | to | both\n" "* `asks` = `any` | ASK[:ASK]*\n"
" ASKS = ASK[:ASK]* | any\n" "* `users` = `any` | JID[:JID]*\n"
" ASK = none | out | in\n" "* `contacts` = `any` | JID[:JID]*\n"
" USERS = JID[:JID]* | any\n" "\nwhere\n\n"
" CONTACTS = JID[:JID]* | any\n" "* SUB = `none` | `from `| `to` | `both`\n"
" JID = characters valid in a JID, and can use the " "* ASK = `none` | `out` | `in`\n"
"globs: *, ?, ! and [...]\n" "* JID = characters valid in a JID, and can use the "
"globs: `*`, `?`, `!` and `[...]`\n"
"\n" "\n"
"This example will list roster items with subscription " "This example will list roster items with subscription "
"'none', 'from' or 'to' that have any ask property, of " "`none`, `from` or `to` that have any ask property, of "
"local users which JID is in the virtual host " "local users which JID is in the virtual host "
"'example.org' and that the contact JID is either a " "`example.org` and that the contact JID is either a "
"bare server name (without user part) or that has a " "bare server name (without user part) or that has a "
"user part and the server part contains the word 'icq'" "user part and the server part contains the word `icq`"
":\n list none:from:to any *@example.org *:*@*icq*" ":\n `list none:from:to any *@example.org *:*@*icq*`"
"\n\n" "\n\n"
" *** SQL:\n" "**SQL backend:**\n"
"\n" "\n"
"Allowed values in the arguments:\n" "Allowed values in the arguments:\n\n"
" ACTION = list | delete\n" "* `action` = `list` | `delete`\n"
" SUBS = any | none | from | to | both\n" "* `subs` = `any` | SUB\n"
" ASKS = any | none | out | in\n" "* `asks` = `any` | ASK\n"
" USERS = JID\n" "* `users` = JID\n"
" CONTACTS = JID\n" "* `contacts` = JID\n"
" JID = characters valid in a JID, and can use the " "\nwhere\n\n"
"globs: _ and %\n" "* SUB = `none` | `from` | `to` | `both`\n"
"* ASK = `none` | `out` | `in`\n"
"* JID = characters valid in a JID, and can use the "
"globs: `_` and `%`\n"
"\n" "\n"
"This example will list roster items with subscription " "This example will list roster items with subscription "
"'to' that have any ask property, of " "`to` that have any ask property, of "
"local users which JID is in the virtual host " "local users which JID is in the virtual host "
"'example.org' and that the contact JID's " "`example.org` and that the contact JID's "
"server part contains the word 'icq'" "server part contains the word `icq`"
":\n list to any %@example.org %@%icq%", ":\n `list to any %@example.org %@%icq%`",
module = mod_roster, function = process_rosteritems, module = mod_roster, function = process_rosteritems,
args = [{action, string}, {subs, string}, args = [{action, string}, {subs, string},
{asks, string}, {users, string}, {asks, string}, {users, string},
@ -569,8 +573,8 @@ get_commands_spec() ->
#ejabberd_commands{name = get_roster, tags = [roster], #ejabberd_commands{name = get_roster, tags = [roster],
desc = "Get list of contacts in a local user roster", desc = "Get list of contacts in a local user roster",
longdesc = longdesc =
"Subscription can be: \"none\", \"from\", \"to\", \"both\". " "`subscription` can be: `none`, `from`, `to`, `both`.\n\n"
"Pending can be: \"in\", \"out\", \"none\".", "`pending` can be: `in`, `out`, `none`.",
note = "improved in 23.10", note = "improved in 23.10",
policy = user, policy = user,
module = ?MODULE, function = get_roster, module = ?MODULE, function = get_roster,
@ -586,11 +590,12 @@ get_commands_spec() ->
#ejabberd_commands{name = push_roster, tags = [roster], #ejabberd_commands{name = push_roster, tags = [roster],
desc = "Push template roster from file to a user", desc = "Push template roster from file to a user",
longdesc = "The text file must contain an erlang term: a list " longdesc = "The text file must contain an erlang term: a list "
"of tuples with username, servername, group and nick. Example:\n" "of tuples with username, servername, group and nick. For example:\n"
"[{<<\"user1\">>, <<\"localhost\">>, <<\"Workers\">>, <<\"User 1\">>},\n" "`[{\"user1\", \"localhost\", \"Workers\", \"User 1\"},\n"
" {<<\"user2\">>, <<\"localhost\">>, <<\"Workers\">>, <<\"User 2\">>}].\n" " {\"user2\", \"localhost\", \"Workers\", \"User 2\"}].`\n\n"
"When using UTF8 character encoding add /utf8 to certain string. Example:\n" "If there are problems parsing UTF8 character encoding, "
"[{<<\"user2\">>, <<\"localhost\">>, <<\"Workers\"/utf8>>, <<\"User 2\"/utf8>>}].", "provide the corresponding string with the `<<\"STRING\"/utf8>>` syntax, for example:\n"
"`[{\"user2\", \"localhost\", \"Workers\", <<\"User 2\"/utf8>>}]`.",
module = ?MODULE, function = push_roster, module = ?MODULE, function = push_roster,
args = [{file, binary}, {user, binary}, {host, binary}], args = [{file, binary}, {user, binary}, {host, binary}],
args_example = [<<"/home/ejabberd/roster.txt">>, <<"user1">>, <<"localhost">>], args_example = [<<"/home/ejabberd/roster.txt">>, <<"user1">>, <<"localhost">>],
@ -600,8 +605,8 @@ get_commands_spec() ->
desc = "Push template roster from file to all those users", desc = "Push template roster from file to all those users",
longdesc = "The text file must contain an erlang term: a list " longdesc = "The text file must contain an erlang term: a list "
"of tuples with username, servername, group and nick. Example:\n" "of tuples with username, servername, group and nick. Example:\n"
"[{\"user1\", \"localhost\", \"Workers\", \"User 1\"},\n" "`[{\"user1\", \"localhost\", \"Workers\", \"User 1\"},\n"
" {\"user2\", \"localhost\", \"Workers\", \"User 2\"}].", " {\"user2\", \"localhost\", \"Workers\", \"User 2\"}].`",
module = ?MODULE, function = push_roster_all, module = ?MODULE, function = push_roster_all,
args = [{file, binary}], args = [{file, binary}],
args_example = [<<"/home/ejabberd/roster.txt">>], args_example = [<<"/home/ejabberd/roster.txt">>],
@ -617,7 +622,9 @@ get_commands_spec() ->
#ejabberd_commands{name = get_last, tags = [last], #ejabberd_commands{name = get_last, tags = [last],
desc = "Get last activity information", desc = "Get last activity information",
longdesc = "Timestamp is UTC and XEP-0082 format, for example: " longdesc = "Timestamp is UTC and "
"[XEP-0082](https://xmpp.org/extensions/xep-0082.html)"
" format, for example: "
"`2017-02-23T22:25:28.063062Z ONLINE`", "`2017-02-23T22:25:28.063062Z ONLINE`",
module = ?MODULE, function = get_last, module = ?MODULE, function = get_last,
args = [{user, binary}, {host, binary}], args = [{user, binary}, {host, binary}],
@ -775,7 +782,9 @@ get_commands_spec() ->
result = {res, rescode}}, result = {res, rescode}},
#ejabberd_commands{name = stats, tags = [statistics], #ejabberd_commands{name = stats, tags = [statistics],
desc = "Get statistical value: registeredusers onlineusers onlineusersnode uptimeseconds processes", desc = "Get some statistical value for the whole ejabberd server",
longdesc = "Allowed statistics `name` are: `registeredusers`, "
"`onlineusers`, `onlineusersnode`, `uptimeseconds`, `processes`.",
policy = admin, policy = admin,
module = ?MODULE, function = stats, module = ?MODULE, function = stats,
args = [{name, binary}], args = [{name, binary}],
@ -785,7 +794,8 @@ get_commands_spec() ->
result_desc = "Integer statistic value", result_desc = "Integer statistic value",
result = {stat, integer}}, result = {stat, integer}},
#ejabberd_commands{name = stats_host, tags = [statistics], #ejabberd_commands{name = stats_host, tags = [statistics],
desc = "Get statistical value for this host: registeredusers onlineusers", desc = "Get some statistical value for this host",
longdesc = "Allowed statistics `name` are: `registeredusers`, `onlineusers`.",
policy = admin, policy = admin,
module = ?MODULE, function = stats, module = ?MODULE, function = stats,
args = [{name, binary}, {host, binary}], args = [{name, binary}, {host, binary}],

10
src/mod_muc_admin.erl
View File

@ -93,10 +93,11 @@ depends(_Host, _Opts) ->
get_commands_spec() -> get_commands_spec() ->
[ [
#ejabberd_commands{name = muc_online_rooms, tags = [muc], #ejabberd_commands{name = muc_online_rooms, tags = [muc],
desc = "List existing rooms ('global' to get all vhosts)", desc = "List existing rooms",
longdesc = "Ask for a specific host, or `global` to use all vhosts.",
policy = admin, policy = admin,
module = ?MODULE, function = muc_online_rooms, module = ?MODULE, function = muc_online_rooms,
args_desc = ["MUC service, or 'global' for all"], args_desc = ["MUC service, or `global` for all"],
args_example = ["muc.example.com"], args_example = ["muc.example.com"],
result_desc = "List of rooms", result_desc = "List of rooms",
result_example = ["room1@muc.example.com", "room2@muc.example.com"], result_example = ["room1@muc.example.com", "room2@muc.example.com"],
@ -104,10 +105,11 @@ get_commands_spec() ->
args_rename = [{host, service}], args_rename = [{host, service}],
result = {rooms, {list, {room, string}}}}, result = {rooms, {list, {room, string}}}},
#ejabberd_commands{name = muc_online_rooms_by_regex, tags = [muc], #ejabberd_commands{name = muc_online_rooms_by_regex, tags = [muc],
desc = "List existing rooms ('global' to get all vhosts) by regex", desc = "List existing rooms filtered by regexp",
longdesc = "Ask for a specific host, or `global` to use all vhosts.",
policy = admin, policy = admin,
module = ?MODULE, function = muc_online_rooms_by_regex, module = ?MODULE, function = muc_online_rooms_by_regex,
args_desc = ["MUC service, or 'global' for all", args_desc = ["MUC service, or `global` for all",
"Regex pattern for room name"], "Regex pattern for room name"],
args_example = ["muc.example.com", "^prefix"], args_example = ["muc.example.com", "^prefix"],
result_desc = "List of rooms with summary", result_desc = "List of rooms with summary",