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

Improve syntax of many command descriptions for the Docs site

Browse Source
This commit is contained in:
Badlop 2023-08-14 13:59:43 +02:00
parent f8af3a0005
commit a84fbd6a74
5 changed files with 65 additions and 56 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
src/ejabberd_admin.erl
View File

@ -140,8 +140,8 @@ get_commands_spec() ->
desc = "Inform users and rooms, wait, and stop the server",
longdesc = "Provide the delay in seconds, and the "
"announcement quoted, for example: \n"
"ejabberdctl stop_kindly 60 "
"\\\"The server will stop in one minute.\\\"",
"`ejabberdctl stop_kindly 60 "
"\\\"The server will stop in one minute.\\\"`",
module = ?MODULE, function = stop_kindly,
args_desc = ["Seconds to wait", "Announcement to send, with quotes"],
args_example = [60, <<"Server will stop now.">>],
@ -292,8 +292,9 @@ get_commands_spec() ->
args = [{host, binary}], result = {res, rescode}},
#ejabberd_commands{name = import_prosody, tags = [mnesia, sql],
desc = "Import data from Prosody",
longdesc = "Note: this requires ejabberd compiled with --enable-lua "
"and include the optional 'luerl' library.",
longdesc = "Note: this requires ejabberd to be "
"[compiled with `--enable-lua`](http://localhost:8098/admin/installation/#configure) "
"(which installs the `luerl` library).",
module = prosody2ejabberd, function = from_dir,
args_desc = ["Full path to the Prosody data directory"],
args_example = ["/var/lib/prosody/datadump/"],
@ -371,7 +372,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 you provide as nodename `self`, 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"],
@ -399,7 +400,7 @@ get_commands_spec() ->
"binary backup file the internal Mnesia "
"database. This will consume a lot of memory if "
"you have a large database, you may prefer "
"'install_fallback'.",
"http://./#install-fallback[install_fallback].",
module = ?MODULE, function = restore_mnesia,
args_desc = ["Full path to the backup file"],
args_example = ["/var/lib/ejabberd/database.backup"],
@ -421,8 +422,9 @@ get_commands_spec() ->
longdesc = "Restore immediately. This is not "
"recommended for big databases, as it will "
"consume much time, memory and processor. In "
"that case it's preferable to use 'backup' and "
"'install_fallback'.",
"that case it's preferable to use "
"http://./#backup[backup] and "
"http://./#install-fallback[install_fallback].",
module = ?MODULE, function = load_mnesia,
args_desc = ["Full path to the text file"],
args_example = ["/var/lib/ejabberd/database.txt"],
@ -444,8 +446,8 @@ get_commands_spec() ->
"restore the database at the next ejabberd "
"start. This means that, after running this "
"command, you have to restart ejabberd. This "
"command requires less memory than
'restore'.",
"command requires less memory than "
"http://./#restore[restore].",
module = ?MODULE, function = install_fallback_mnesia,
args_desc = ["Full path to the fallback file"],
args_example = ["/var/lib/ejabberd/database.fallback"],

4
src/ejabberd_commands.erl
View File

@ -73,7 +73,7 @@ get_commands_spec() ->
"documentation should be stored",
"Regexp matching names of commands or modules "
"that will be included inside generated document",
"Comma separated list of languages (chosen from java, perl, xmlrpc, json)"
"Comma separated list of languages (chosen from `java`, `perl`, `xmlrpc`, `json`) "
"that will have example invocation include in markdown document"],
result_desc = "0 if command failed, 1 when succeeded",
args_example = ["/home/me/docs/api.html", "mod_admin", "java,json"],
@ -87,7 +87,7 @@ get_commands_spec() ->
"documentation should be stored",
"Regexp matching names of commands or modules "
"that will be included inside generated document",
"Comma separated list of languages (chosen from java, perl, xmlrpc, json)"
"Comma separated list of languages (chosen from `java`, `perl`, `xmlrpc`, `json`) "
"that will have example invocation include in markdown document"],
result_desc = "0 if command failed, 1 when succeeded",
args_example = ["/home/me/docs/api.html", "mod_admin", "java,json"],

51
src/mod_admin_extra.erl
View File

@ -169,10 +169,12 @@ get_commands_spec() ->
#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"
"```\n"
"access_rules:\n"
" protect_old_users:\n"
" - allow: admin\n"
" - deny: all\n",
" - deny: all\n"
"```\n",
module = ?MODULE, function = delete_old_users,
args = [{days, integer}],
args_example = [30],
@ -183,10 +185,12 @@ get_commands_spec() ->
#ejabberd_commands{name = delete_old_users_vhost, tags = [accounts, purge],
desc = "Delete users that didn't log in last days in vhost, or that never logged",
longdesc = "To protect admin accounts, configure this for example:\n"
"```\n"
"access_rules:\n"
" delete_old_users:\n"
" - deny: admin\n"
" - allow: all\n",
" - allow: all\n"
"```\n",
module = ?MODULE, function = delete_old_users_vhost,
args = [{host, binary}, {days, integer}],
args_example = [<<"myserver.com">>, 30],
@ -215,7 +219,8 @@ get_commands_spec() ->
result_desc = "Status code: 0 on success, 1 otherwise"},
#ejabberd_commands{name = check_password_hash, tags = [accounts],
desc = "Check if the password hash is correct",
longdesc = "Allows hash methods from crypto application",
longdesc = "Allows hash methods from the Erlang/OTP "
"[crypto](https://www.erlang.org/doc/man/crypto) application.",
module = ?MODULE, function = check_password_hash,
args = [{user, binary}, {host, binary}, {passwordhash, binary},
{hashmethod, binary}],
@ -390,14 +395,14 @@ get_commands_spec() ->
"and its presence (show and status message) "
"for a given user.",
longdesc =
"The 'jid' value contains the user jid "
"with resource.\nThe 'show' value contains "
"The `jid` value contains the user JID "
"with resource.\n\nThe `show` value contains "
"the user presence flag. It can take "
"limited values:\n - available\n - chat "
"(Free for chat)\n - away\n - dnd (Do "
"not disturb)\n - xa (Not available, "
"extended away)\n - unavailable (Not "
"connected)\n\n'status' is a free text "
"limited values:\n\n - `available`\n - `chat` "
"(Free for chat)\n - `away`\n - `dnd` (Do "
"not disturb)\n - `xa` (Not available, "
"extended away)\n - `unavailable` (Not "
"connected)\n\n`status` is a free text "
"defined by the user client.",
module = ?MODULE, function = get_presence,
args = [{user, binary}, {host, binary}],
@ -421,8 +426,8 @@ get_commands_spec() ->
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",
"Type: `available`, `error`, `probe`...",
"Show: `away`, `chat`, `dnd`, `xa`.", "Status text",
"Priority, provide this value as an integer"],
result = {res, rescode}},
@ -485,7 +490,7 @@ get_commands_spec() ->
#ejabberd_commands{name = add_rosteritem, tags = [roster],
desc = "Add an item to a user's roster (supports ODBC)",
longdesc = "Group can be several groups separated by ; for example: \"g1;g2;g3\"",
longdesc = "Group can be several groups separated by `;` for example: `g1;g2;g3`",
module = ?MODULE, function = add_rosteritem,
args = [{localuser, binary}, {localhost, binary},
{user, binary}, {host, binary},
@ -616,7 +621,7 @@ 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: "
"2017-02-23T22:25:28.063062Z ONLINE",
"`2017-02-23T22:25:28.063062Z ONLINE`",
module = ?MODULE, function = get_last,
args = [{user, binary}, {host, binary}],
args_example = [<<"user1">>,<<"myserver.com">>],
@ -630,7 +635,7 @@ get_commands_spec() ->
#ejabberd_commands{name = set_last, tags = [last],
desc = "Set last activity information",
longdesc = "Timestamp is the seconds since "
"1970-01-01 00:00:00 UTC, for example: date +%s",
"`1970-01-01 00:00:00 UTC`. For example value see `date +%s`",
module = ?MODULE, function = set_last,
args = [{user, binary}, {host, binary}, {timestamp, integer}, {status, binary}],
args_example = [<<"user1">>,<<"myserver.com">>, 1500045311, <<"GoSleeping">>],
@ -657,11 +662,11 @@ get_commands_spec() ->
desc = "Create a Shared Roster Group",
longdesc = "If you want to specify several group "
"identifiers in the Display argument,\n"
"put \\ \" around the argument and\nseparate the "
"identifiers with \\ \\ n\n"
"put `\\ \"` around the argument and\nseparate the "
"identifiers with `\\ \\ n`\n"
"For example:\n"
" ejabberdctl srg_create group3 myserver.com "
"name desc \\\"group1\\\\ngroup2\\\"",
" `ejabberdctl srg_create group3 myserver.com "
"name desc \\\"group1\\\\ngroup2\\\"`",
note = "changed in 21.07",
module = ?MODULE, function = srg_create,
args = [{group, binary}, {host, binary},
@ -734,7 +739,7 @@ get_commands_spec() ->
#ejabberd_commands{name = send_message, tags = [stanza],
desc = "Send a message to a local or remote bare of full JID",
longdesc = "When sending a groupchat message to a MUC room, "
"FROM must be the full JID of a room occupant, "
"`from` must be the full JID of a room occupant, "
"or the bare JID of a MUC service admin, "
"or the bare JID of a MUC/Sub subscribed user.",
module = ?MODULE, function = send_message,
@ -742,13 +747,13 @@ get_commands_spec() ->
{subject, binary}, {body, binary}],
args_example = [<<"headline">>, <<"admin@localhost">>, <<"user1@localhost">>,
<<"Restart">>, <<"In 5 minutes">>],
args_desc = ["Message type: normal, chat, headline, groupchat", "Sender JID",
args_desc = ["Message type: `normal`, `chat`, `headline`, `groupchat`", "Sender JID",
"Receiver JID", "Subject, or empty string", "Body"],
result = {res, rescode}},
#ejabberd_commands{name = send_stanza_c2s, tags = [stanza],
desc = "Send a stanza from an existing C2S session",
longdesc = "USER@HOST/RESOURCE must be an existing C2S session."
" As an alternative, use send_stanza instead.",
longdesc = "`user`@`host`/`resource` must be an existing C2S session."
" As an alternative, use http://./#send-stanza[send_stanza] instead.",
module = ?MODULE, function = send_stanza_c2s,
args = [{user, binary}, {host, binary}, {resource, binary}, {stanza, binary}],
args_example = [<<"admin">>, <<"myserver.com">>, <<"bot">>,

8
src/mod_mam.erl
View File

@ -1468,9 +1468,9 @@ get_commands_spec() ->
[#ejabberd_commands{name = delete_old_mam_messages, tags = [purge],
desc = "Delete MAM messages older than DAYS",
longdesc = "Valid message TYPEs: "
"\"chat\", \"groupchat\", \"all\".",
"`chat`, `groupchat`, `all`.",
module = ?MODULE, function = delete_old_messages,
args_desc = ["Type of messages to delete (chat, groupchat, all)",
args_desc = ["Type of messages to delete (`chat`, `groupchat`, `all`)",
"Days to keep messages"],
args_example = [<<"all">>, 31],
args = [{type, binary}, {days, integer}],
@ -1479,10 +1479,10 @@ get_commands_spec() ->
desc = "Delete MAM messages older than DAYS",
note = "added in 22.05",
longdesc = "Valid message TYPEs: "
"\"chat\", \"groupchat\", \"all\".",
"`chat`, `groupchat`, `all`.",
module = ?MODULE, function = delete_old_messages_batch,
args_desc = ["Name of host where messages should be deleted",
"Type of messages to delete (chat, groupchat, all)",
"Type of messages to delete (`chat`, `groupchat`, `all`)",
"Days to keep messages",
"Number of messages to delete per batch",
"Desired rate of messages to delete per minute"],

36
src/mod_muc_admin.erl
View File

@ -163,8 +163,8 @@ get_commands_spec() ->
#ejabberd_commands{name = create_room_with_opts, tags = [muc_room],
desc = "Create a MUC room name@service in host with given options",
longdesc =
"The syntax of affiliations is: 'Type:JID,Type:JID'. "
"The syntax of subscribers is: 'JID:Nick:Node:Node2,JID:Nick:Node' ",
"The syntax of `affiliations` is: `Type:JID,Type:JID`. "
"The syntax of `subscribers` is: `JID:Nick:Node:Node2:Node3,JID:Nick:Node`.",
module = ?MODULE, function = create_room_with_opts,
args_desc = ["Room name", "MUC service", "Server host", "List of options"],
args_example = ["room1", "muc.example.com", "localhost",
@ -192,9 +192,9 @@ get_commands_spec() ->
desc = "List the rooms that are unused for many days in the service",
longdesc = "The room recent history is used, so it's recommended "
" to wait a few days after service start before running this."
" The MUC service argument can be 'global' to get all hosts.",
" The MUC service argument can be `global` to get all hosts.",
module = ?MODULE, function = rooms_unused_list,
args_desc = ["MUC service, or 'global' for all", "Number of days"],
args_desc = ["MUC service, or `global` for all", "Number of days"],
args_example = ["muc.example.com", 31],
result_desc = "List of unused rooms",
result_example = ["room1@muc.example.com", "room2@muc.example.com"],
@ -205,9 +205,9 @@ get_commands_spec() ->
desc = "Destroy the rooms that are unused for many days in the service",
longdesc = "The room recent history is used, so it's recommended "
" to wait a few days after service start before running this."
" The MUC service argument can be 'global' to get all hosts.",
" The MUC service argument can be `global` to get all hosts.",
module = ?MODULE, function = rooms_unused_destroy,
args_desc = ["MUC service, or 'global' for all", "Number of days"],
args_desc = ["MUC service, or `global` for all", "Number of days"],
args_example = ["muc.example.com", 31],
result_desc = "List of unused rooms that has been destroyed",
result_example = ["room1@muc.example.com", "room2@muc.example.com"],
@ -217,9 +217,9 @@ get_commands_spec() ->
#ejabberd_commands{name = rooms_empty_list, tags = [muc],
desc = "List the rooms that have no messages in archive",
longdesc = "The MUC service argument can be 'global' to get all hosts.",
longdesc = "The MUC service argument can be `global` to get all hosts.",
module = ?MODULE, function = rooms_empty_list,
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 empty rooms",
result_example = ["room1@muc.example.com", "room2@muc.example.com"],
@ -228,9 +228,9 @@ get_commands_spec() ->
result = {rooms, {list, {room, string}}}},
#ejabberd_commands{name = rooms_empty_destroy, tags = [muc],
desc = "Destroy the rooms that have no messages in archive",
longdesc = "The MUC service argument can be 'global' to get all hosts.",
longdesc = "The MUC service argument can be `global` to get all hosts.",
module = ?MODULE, function = rooms_empty_destroy,
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 empty rooms that have been destroyed",
result_example = ["room1@muc.example.com", "room2@muc.example.com"],
@ -295,11 +295,11 @@ get_commands_spec() ->
longdesc = "Since ejabberd 20.12, this command is "
"asynchronous: the API call may return before the "
"server has send all the invitations.\n\n"
"Password and Message can also be: none. "
"Users JIDs are separated with : ",
"Password and Message can also be: `none`. "
"Users JIDs are separated with `:`.",
module = ?MODULE, function = send_direct_invitation,
args_desc = ["Room name", "MUC service", "Password, or none",
"Reason text, or none", "Users JIDs separated with : characters"],
args_desc = ["Room name", "MUC service", "Password, or `none`",
"Reason text, or `none`", "Users JIDs separated with `:` characters"],
args_example = [<<"room1">>, <<"muc.example.com">>,
<<>>, <<"Check this out!">>,
"user2@localhost:user3@example.com"],
@ -333,7 +333,7 @@ get_commands_spec() ->
desc = "Subscribe to a MUC conference",
module = ?MODULE, function = subscribe_room,
args_desc = ["User JID", "a user's nick",
"the room to subscribe", "nodes separated by commas: ,"],
"the room to subscribe", "nodes separated by commas: `,`"],
args_example = ["tom@localhost", "Tom", "room1@conference.localhost",
"urn:xmpp:mucsub:nodes:messages,urn:xmpp:mucsub:nodes:affiliations"],
result_desc = "The list of nodes that has subscribed",
@ -345,11 +345,13 @@ get_commands_spec() ->
#ejabberd_commands{name = subscribe_room_many, tags = [muc_room],
desc = "Subscribe several users to a MUC conference",
note = "added in 22.05",
longdesc = "This command accept up to 50 users at once (this is configurable with `subscribe_room_many_max_users` option)",
longdesc = "This command accepts up to 50 users at once "
"(this is configurable with the *`mod_muc_admin`* option "
"`subscribe_room_many_max_users`)",
module = ?MODULE, function = subscribe_room_many,
args_desc = ["Users JIDs and nicks",
"the room to subscribe",
"nodes separated by commas: ,"],
"nodes separated by commas: `,`"],
args_example = [[{"tom@localhost", "Tom"},
{"jerry@localhost", "Jerry"}],
"room1@conference.localhost",