Chapril
/
xmpp.chapril.org-ejabberd
mirror of https://github.com/processone/ejabberd.git
24
1
Fork 0
Code Releases Activity

Commands: Improve syntax of many commands documentation

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() ->
[#ejabberd_commands{name = request_certificate, tags = [acme],
desc = "Requests certificates for all or the specified "
"domains: all | domain1,domain2,...",
desc = "Requests certificates for all or some domains",
longdesc = "Domains can be `all`, or a list of domains separared with comma characters",
module = ?MODULE, function = request_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}],
result = {res, restuple}},
#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",
longdesc = "This can be useful when an external tool is "
"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,
module = ?MODULE, function = reopen_log,
args = [], result = {res, rescode}},
@ -157,9 +157,10 @@ get_commands_spec() ->
result = {levelatom, atom}},
#ejabberd_commands{name = set_loglevel, tags = [logs],
desc = "Set the loglevel",
longdesc = "Possible loglevels: `none`, `emergency`, `alert`, `critical`,
`error`, `warning`, `notice`, `info`, `debug`.",
module = ?MODULE, function = set_loglevel,
args_desc = ["Desired logging level: none | emergency | alert | critical "
"| error | warning | notice | info | debug"],
args_desc = ["Desired logging level"],
args_example = ["debug"],
args = [{loglevel, string}],
result = {res, rescode}},
@ -171,7 +172,8 @@ get_commands_spec() ->
result_example = ["mod_configure", "mod_vcard"],
result = {modules, {list, {module, string}}}},
#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,
args_example = ["mod_vcard"],
args = [{module, string}],
@ -373,7 +375,7 @@ get_commands_spec() ->
result = {res, rescode}},
#ejabberd_commands{name = set_master, tags = [cluster],
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.",
module = ?MODULE, function = set_master,
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() ->
[
#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,
args = [{jid, string},{ttl, integer}, {scopes, string}],
policy = restricted,
@ -92,15 +92,15 @@ get_commands_spec() ->
result = {result, {tuple, [{token, string}, {scopes, string}, {expires_in, string}]}}
},
#ejabberd_commands{name = oauth_list_tokens, tags = [oauth],
desc = "List 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",
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",
module = ?MODULE, function = oauth_list_tokens,
args = [],
policy = restricted,
result = {tokens, {list, {token, {tuple, [{token, string}, {user, string}, {scope, string}, {expires_in, string}]}}}}
},
#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",
module = ?MODULE, function = oauth_revoke_token,
args = [{token, binary}],
@ -109,7 +109,7 @@ get_commands_spec() ->
result_desc = "Result code"
},
#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,
args = [{client_id, binary},
{client_name, binary},
@ -118,7 +118,7 @@ get_commands_spec() ->
result = {res, restuple}
},
#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,
args = [{client_id, binary},
{client_name, binary},
@ -127,7 +127,7 @@ get_commands_spec() ->
result = {res, restuple}
},
#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,
args = [{client_id, binary}],
policy = restricted,

116
src/mod_admin_extra.erl
View File

@ -113,14 +113,14 @@ depends(_Host, _Opts) ->
%%%
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"
"* NICKNAME - Nickname\n"
"* BDAY - Birthday\n"
"* TITLE - Work: Position\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 GIVEN - Given name\n"
"* N MIDDLE - Middle name\n"
@ -134,8 +134,8 @@ get_commands_spec() ->
"* ORG ORGNAME - Work: Company\n"
"* ORG ORGUNIT - Work: Department\n",
VcardXEP = "For a full list of vCard fields check XEP-0054: vcard-temp at "
"https://xmpp.org/extensions/xep-0054.html",
VcardXEP = "For a full list of vCard fields check [XEP-0054: vcard-temp]"
"(https://xmpp.org/extensions/xep-0054.html)",
[
#ejabberd_commands{name = compile, tags = [erlang],
@ -162,9 +162,9 @@ get_commands_spec() ->
result = {res, integer},
result_example = 0,
result_desc = "Returns integer code:\n"
" - 0: code reloaded, module restarted\n"
" - 1: error: module not loaded\n"
" - 2: code not reloaded, but module restarted"},
" - `0`: code reloaded, module restarted\n"
" - `1`: error: module not loaded\n"
" - `2`: code not reloaded, but module restarted"},
#ejabberd_commands{name = delete_old_users, tags = [accounts, purge],
desc = "Delete users that didn't log in last days, or that never logged",
longdesc = "To protect admin accounts, configure this for example:\n"
@ -509,52 +509,56 @@ get_commands_spec() ->
result = {res, rescode}},
#ejabberd_commands{name = process_rosteritems, tags = [roster],
desc = "List/delete rosteritems that match filter",
longdesc = "Explanation of each argument:\n"
" - action: what to do with each rosteritem that "
longdesc = "Explanation of each argument:\n\n"
"* `action`: what to do with each rosteritem that "
"matches all the filtering options\n"
" - subs: subscription type\n"
" - asks: pending subscription\n"
" - users: the JIDs of the local user\n"
" - contacts: the JIDs of the contact in the roster\n"
"* `subs`: subscription type\n"
"* `asks`: pending subscription\n"
"* `users`: the JIDs of the local user\n"
"* `contacts`: the JIDs of the contact in the roster\n"
"\n"
" *** Mnesia: \n"
"**Mnesia backend:**\n"
"\n"
"Allowed values in the arguments:\n"
" ACTION = list | delete\n"
" SUBS = SUB[:SUB]* | any\n"
" SUB = none | from | to | both\n"
" ASKS = ASK[:ASK]* | any\n"
" ASK = none | out | in\n"
" USERS = JID[:JID]* | any\n"
" CONTACTS = JID[:JID]* | any\n"
" JID = characters valid in a JID, and can use the "
"globs: *, ?, ! and [...]\n"
"Allowed values in the arguments:\n\n"
"* `action` = `list` | `delete`\n"
"* `subs` = `any` | SUB[:SUB]*\n"
"* `asks` = `any` | ASK[:ASK]*\n"
"* `users` = `any` | JID[:JID]*\n"
"* `contacts` = `any` | JID[:JID]*\n"
"\nwhere\n\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"
"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 "
"'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 "
"user part and the server part contains the word 'icq'"
":\n list none:from:to any *@example.org *:*@*icq*"
"user part and the server part contains the word `icq`"
":\n `list none:from:to any *@example.org *:*@*icq*`"
"\n\n"
" *** SQL:\n"
"**SQL backend:**\n"
"\n"
"Allowed values in the arguments:\n"
" ACTION = list | delete\n"
" SUBS = any | none | from | to | both\n"
" ASKS = any | none | out | in\n"
" USERS = JID\n"
" CONTACTS = JID\n"
" JID = characters valid in a JID, and can use the "
"globs: _ and %\n"
"Allowed values in the arguments:\n\n"
"* `action` = `list` | `delete`\n"
"* `subs` = `any` | SUB\n"
"* `asks` = `any` | ASK\n"
"* `users` = JID\n"
"* `contacts` = JID\n"
"\nwhere\n\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"
"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 "
"'example.org' and that the contact JID's "
"server part contains the word 'icq'"
":\n list to any %@example.org %@%icq%",
"`example.org` and that the contact JID's "
"server part contains the word `icq`"
":\n `list to any %@example.org %@%icq%`",
module = mod_roster, function = process_rosteritems,
args = [{action, string}, {subs, string},
{asks, string}, {users, string},
@ -569,8 +573,8 @@ get_commands_spec() ->
#ejabberd_commands{name = get_roster, tags = [roster],
desc = "Get list of contacts in a local user roster",
longdesc =
"Subscription can be: \"none\", \"from\", \"to\", \"both\". "
"Pending can be: \"in\", \"out\", \"none\".",
"`subscription` can be: `none`, `from`, `to`, `both`.\n\n"
"`pending` can be: `in`, `out`, `none`.",
note = "improved in 23.10",
policy = user,
module = ?MODULE, function = get_roster,
@ -586,11 +590,12 @@ 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\">>}].\n"
"When using UTF8 character encoding add /utf8 to certain string. Example:\n"
"[{<<\"user2\">>, <<\"localhost\">>, <<\"Workers\"/utf8>>, <<\"User 2\"/utf8>>}].",
"of tuples with username, servername, group and nick. For example:\n"
"`[{\"user1\", \"localhost\", \"Workers\", \"User 1\"},\n"
" {\"user2\", \"localhost\", \"Workers\", \"User 2\"}].`\n\n"
"If there are problems parsing UTF8 character encoding, "
"provide the corresponding string with the `<<\"STRING\"/utf8>>` syntax, for example:\n"
"`[{\"user2\", \"localhost\", \"Workers\", <<\"User 2\"/utf8>>}]`.",
module = ?MODULE, function = push_roster,
args = [{file, binary}, {user, binary}, {host, binary}],
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",
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\"}].",
"`[{\"user1\", \"localhost\", \"Workers\", \"User 1\"},\n"
" {\"user2\", \"localhost\", \"Workers\", \"User 2\"}].`",
module = ?MODULE, function = push_roster_all,
args = [{file, binary}],
args_example = [<<"/home/ejabberd/roster.txt">>],
@ -617,7 +622,9 @@ get_commands_spec() ->
#ejabberd_commands{name = get_last, tags = [last],
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`",
module = ?MODULE, function = get_last,
args = [{user, binary}, {host, binary}],
@ -775,7 +782,9 @@ get_commands_spec() ->
result = {res, rescode}},
#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,
module = ?MODULE, function = stats,
args = [{name, binary}],
@ -785,7 +794,8 @@ get_commands_spec() ->
result_desc = "Integer statistic value",
result = {stat, integer}},
#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,
module = ?MODULE, function = stats,
args = [{name, binary}, {host, binary}],

10
src/mod_muc_admin.erl
View File

@ -93,10 +93,11 @@ depends(_Host, _Opts) ->
get_commands_spec() ->
[
#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,
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"],
result_desc = "List of rooms",
result_example = ["room1@muc.example.com", "room2@muc.example.com"],
@ -104,10 +105,11 @@ get_commands_spec() ->
args_rename = [{host, service}],
result = {rooms, {list, {room, string}}}},
#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,
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"],
args_example = ["muc.example.com", "^prefix"],
result_desc = "List of rooms with summary",