From f3c935d2e10c9aa69e1eb7007a4fb5795b33686a Mon Sep 17 00:00:00 2001 From: Badlop Date: Thu, 5 Dec 2024 16:42:46 +0100 Subject: [PATCH] Fix some documentation syntax, add links to toplevel, modules and API --- src/ejabberd_admin.erl | 2 +- src/ejabberd_options_doc.erl | 58 ++++++++++++++++++++--------------- src/mod_admin_extra.erl | 22 ++++++------- src/mod_blocking.erl | 2 +- src/mod_conversejs.erl | 7 ++--- src/mod_delegation.erl | 2 +- src/mod_host_meta.erl | 3 +- src/mod_http_api.erl | 6 ++-- src/mod_http_upload.erl | 36 +++++++++++----------- src/mod_http_upload_quota.erl | 6 ++-- src/mod_mix.erl | 2 +- src/mod_mix_pam.erl | 2 +- src/mod_mqtt_bridge.erl | 29 ++++++++++++------ src/mod_muc.erl | 12 ++++---- src/mod_muc_admin.erl | 2 +- src/mod_offline.erl | 16 +++++----- src/mod_privacy.erl | 4 +-- src/mod_private.erl | 2 +- src/mod_shared_roster.erl | 2 +- 19 files changed, 116 insertions(+), 99 deletions(-) diff --git a/src/ejabberd_admin.erl b/src/ejabberd_admin.erl index f326d05d1..fcfbb840a 100644 --- a/src/ejabberd_admin.erl +++ b/src/ejabberd_admin.erl @@ -297,7 +297,7 @@ get_commands_spec() -> longdesc = "This command can be run from any running " "node of the cluster, even the node to be removed. " "In the removed node, this command works only when " - "using ejabberdctl, not mod_http_api or other code that " + "using ejabberdctl, not _`mod_http_api`_ or other code that " "runs inside the same ejabberd node that will leave.", module = ?MODULE, function = leave_cluster, args_desc = ["Nodename of the node to kick from the cluster"], diff --git a/src/ejabberd_options_doc.erl b/src/ejabberd_options_doc.erl index 4e4bfe242..4a4ade0ed 100644 --- a/src/ejabberd_options_doc.erl +++ b/src/ejabberd_options_doc.erl @@ -403,7 +403,7 @@ doc() -> #{value => "true | false", note => "added in 23.10", desc => - ?T("Supplement check for user existence based on 'mod_last' data, for authentication " + ?T("Supplement check for user existence based on _`mod_last`_ data, for authentication " "methods that don't have a way to reliably tell if a user exists (like is the case for " "'jwt' and certificate based authentication). This helps with processing offline message " "for those users. The default value is 'true'.")}}, @@ -440,8 +440,8 @@ doc() -> desc => ?T("Full path to a file containing custom DH parameters " "to use for c2s connections. " - "Such a file could be created with the command \"openssl " - "dhparam -out dh.pem 2048\". If this option is not specified, " + "Such a file could be created with the command '\"openssl " + "dhparam -out dh.pem 2048\"'. If this option is not specified, " "2048-bit MODP Group with 256-bit Prime Order Subgroup will be " "used as defined in RFC5114 Section 2.3.")}}, {c2s_protocol_options, @@ -500,7 +500,7 @@ doc() -> "If set to 'auto', it builds the URL using a 'request_handler' " "already enabled, with encryption if available. " "If set to 'undefined', it builds the URL using " - "the deprecated _`captcha_host`_ + /captcha. " + "the deprecated _`captcha_host`_ '+ /captcha'. " "The default value is 'auto'.")}}, {certfiles, #{value => "[Path, ...]", @@ -595,17 +595,25 @@ doc() -> " transport.example.org:", " type: bare_source"]}, [{type, - #{value => "random | source | destination | bare_source | bare_destination", + #{value => ?T("Value"), desc => - ?T("How to deliver stanzas to connected components: " - "'random' - an instance is chosen at random; " - "'destination' - an instance is chosen by the full JID of " - "the packet's 'to' attribute; " - "'source' - by the full JID of the packet's 'from' attribute; " - "'bare_destination' - by the bare JID (without resource) " - "of the packet's 'to' attribute; " - "'bare_source' - by the bare JID (without resource) of the " - "packet's 'from' attribute is used. The default value is 'random'.")}}, + ?T("How to deliver stanzas to connected components. " + "The default value is 'random'. Possible values: ")}, + [{'- random', + #{desc => + ?T("an instance is chosen at random")}}, + {'- source', + #{desc => + ?T("by the full JID of the packet's 'from' attribute")}}, + {'- bare_destination', + #{desc => + ?T("by the bare JID (without resource) of the packet's 'to' attribute")}}, + {'- bare_source', + #{desc => + ?T("by the bare JID (without resource) of the packet's 'from' attribute is used")}}, + {'- destination', + #{desc => + ?T("an instance is chosen by the full JID of the packet's 'to' attribute")}}]}, {component_number, #{value => "2..1000", desc => @@ -881,20 +889,20 @@ doc() -> desc => ?T("The size (in bytes) of a log file to trigger rotation. " "If set to 'infinity', log rotation is disabled. " - "The default value is '10485760' (that is, 10 Mb).")}}, + "The default value is 10 Mb expressed in bytes: '10485760'.")}}, {log_burst_limit_count, #{value => ?T("Number"), note => "added in 22.10", desc => ?T("The number of messages to accept in " "`log_burst_limit_window_time` period before starting to " - "drop them. Default 500")}}, + "drop them. Default `500`")}}, {log_burst_limit_window_time, #{value => ?T("Number"), note => "added in 22.10", desc => ?T("The time period to rate-limit log messages " - "by. Defaults to 1 second.")}}, + "by. Defaults to `1` second.")}}, {log_modules_fully, #{value => "[Module, ...]", note => "added in 23.01", @@ -1032,7 +1040,7 @@ doc() -> ?T("Trigger OOM killer when some of the running Erlang processes " "have messages queue above this 'Size'. Note that " "such processes won't be killed if _`oom_killer`_ option is set " - "to 'false' or if 'oom_watermark' is not reached yet.")}}, + "to 'false' or if _`oom_watermark`_ is not reached yet.")}}, {oom_watermark, #{value => ?T("Percent"), desc => @@ -1055,7 +1063,7 @@ doc() -> note => "added in 20.12", desc => ?T("Specify the IPv4 address that will be used when establishing " - "an outgoing S2S IPv4 connection, for example \"127.0.0.1\". " + "an outgoing S2S IPv4 connection, for example '\"127.0.0.1\"'. " "The default value is 'undefined'.")}}, {outgoing_s2s_ipv6_address, #{value => "Address", @@ -1063,7 +1071,7 @@ doc() -> desc => ?T("Specify the IPv6 address that will be used when establishing " "an outgoing S2S IPv6 connection, for example " - "\"::FFFF:127.0.0.1\". The default value is 'undefined'.")}}, + "'\"::FFFF:127.0.0.1\"'. The default value is 'undefined'.")}}, {outgoing_s2s_port, #{value => "1..65535", desc => @@ -1232,8 +1240,8 @@ doc() -> desc => ?T("Full path to a file containing custom DH parameters " "to use for s2s connections. " - "Such a file could be created with the command \"openssl " - "dhparam -out dh.pem 2048\". If this option is not specified, " + "Such a file could be created with the command '\"openssl " + "dhparam -out dh.pem 2048\"'. If this option is not specified, " "2048-bit MODP Group with 256-bit Prime Order Subgroup will be " "used as defined in RFC5114 Section 2.3.")}}, {s2s_protocol_options, @@ -1396,7 +1404,7 @@ doc() -> #{value => ?T("Size"), desc => ?T("Number of connections to the SQL server that ejabberd will " - "open for each virtual host. The default value is 10. WARNING: " + "open for each virtual host. The default value is '10'. WARNING: " "for SQLite this value is '1' by default and it's not recommended " "to change it due to potential race conditions.")}}, {sql_port, @@ -1490,7 +1498,7 @@ doc() -> "possibly with masks. The default value is an empty list. " "Using this option you can know the real IP " "of the request, for admin purpose, or security configuration " - "(for example using 'mod_fail2ban'). IMPORTANT: The proxy MUST " + "(for example using _`mod_fail2ban`_). IMPORTANT: The proxy MUST " "be configured to set the 'X-Forwarded-For' header if you " "enable this option as, otherwise, the client can set it " "itself and as a result the IP value cannot be trusted for " @@ -1513,7 +1521,7 @@ doc() -> "balancer can be chosen for a specific ejabberd implementation " "while still providing a secure WebSocket connection. " "The default value is 'ignore'. An example value of the 'URL' is " - "\"https://test.example.org:8081\".")}}, + "'\"https://test.example.org:8081\"'.")}}, {websocket_ping_interval, #{value => "timeout()", desc => diff --git a/src/mod_admin_extra.erl b/src/mod_admin_extra.erl index 4e644586d..4e203eb83 100644 --- a/src/mod_admin_extra.erl +++ b/src/mod_admin_extra.erl @@ -274,9 +274,9 @@ get_commands_spec() -> longdesc = "This command kicks the account sessions, " "sets a random password, and stores ban details in the " "account private storage. " - "This command requires mod_private to be enabled. " + "This command requires _`mod_private`_ to be enabled. " "Check also _`get_ban_details`_ API " - "and `_unban_account`_ API.", + "and _`unban_account`_ API.", module = ?MODULE, function = ban_account_v2, version = 2, note = "improved in 24.06", @@ -2326,22 +2326,22 @@ mod_doc() -> #{desc => [?T("This module provides additional administrative commands."), "", ?T("Details for some commands:"), "", - ?T("- 'ban_account':"), + ?T("_`ban_account`_ API:"), ?T("This command kicks all the connected sessions of the account " "from the server. It also changes their password to a randomly " "generated one, so they can't login anymore unless a server " "administrator changes their password again. It is possible to " "define the reason of the ban. The new password also includes " - "the reason and the date and time of the ban. See an example below."), - ?T("- 'pushroster': (and 'pushroster-all')"), + "the reason and the date and time of the ban. See an example below."), "", + ?T("_`push_roster`_ API (and _`push_roster_all`_ API):"), ?T("The roster file must be placed, if using Windows, on the " "directory where you installed ejabberd: " "`C:/Program Files/ejabberd` or similar. If you use other " "Operating System, place the file on the same directory where " - "the .beam files are installed. See below an example roster file."), - ?T("- 'srg_create':"), + "the .beam files are installed. See below an example roster file."), "", + ?T("_`srg_create`_ API:"), ?T("If you want to put a group Name with blank spaces, use the " - "characters \"\' and \'\" to define when the Name starts and " + "characters '\"\'' and '\'\"' to define when the Name starts and " "ends. See an example below.")], example => [{?T("With this configuration, vCards can only be modified with " @@ -2356,14 +2356,14 @@ mod_doc() -> " mod_admin_extra: {}", " mod_vcard:", " access_set: vcard_set"]}, - {?T("Content of roster file for 'pushroster' command:"), + {?T("Content of roster file for _`push_roster`_ API:"), ["[{<<\"bob\">>, <<\"example.org\">>, <<\"workers\">>, <<\"Bob\">>},", "{<<\"mart\">>, <<\"example.org\">>, <<\"workers\">>, <<\"Mart\">>},", "{<<\"Rich\">>, <<\"example.org\">>, <<\"bosses\">>, <<\"Rich\">>}]."]}, {?T("With this call, the sessions of the local account which JID is " - "boby@example.org will be kicked, and its password will be set " + "'boby@example.org' will be kicked, and its password will be set " "to something like " "'BANNED_ACCOUNT--20080425T21:45:07--2176635--Spammed_rooms'"), ["ejabberdctl vhost example.org ban_account boby \"Spammed rooms\""]}, - {?T("Call to srg_create using double-quotes and single-quotes:"), + {?T("Call to _`srg_create`_ API using double-quotes and single-quotes:"), ["ejabberdctl srg_create g1 example.org \"\'Group number 1\'\" this_is_g1 g1"]}]}. diff --git a/src/mod_blocking.erl b/src/mod_blocking.erl index 9ed4ce65d..da0913e93 100644 --- a/src/mod_blocking.erl +++ b/src/mod_blocking.erl @@ -269,5 +269,5 @@ mod_doc() -> [?T("The module implements " "https://xmpp.org/extensions/xep-0191.html" "[XEP-0191: Blocking Command]."), "", - ?T("This module depends on 'mod_privacy' where " + ?T("This module depends on _`mod_privacy`_ where " "all the configuration is performed.")]}. diff --git a/src/mod_conversejs.erl b/src/mod_conversejs.erl index 9017720a4..b932d862e 100644 --- a/src/mod_conversejs.erl +++ b/src/mod_conversejs.erl @@ -256,9 +256,8 @@ mod_doc() -> ?T("To use this module, in addition to adding it to the 'modules' " "section, you must also enable it in 'listen' -> 'ejabberd_http' -> " "_`listen-options.md#request_handlers|request_handlers`_."), "", - ?T("Make sure either 'mod_bosh' or 'ejabberd_http_ws' " - "_`listen-options.md#request_handlers|request_handlers`_ " - "are enabled."), "", + ?T("Make sure either _`mod_bosh`_ or _`listen.md#ejabberd_http_ws|ejabberd_http_ws`_ " + "are enabled in at least one 'request_handlers'."), "", ?T("When 'conversejs_css' and 'conversejs_script' are 'auto', " "by default they point to the public Converse client.") ], @@ -308,7 +307,7 @@ mod_doc() -> #{value => ?T("auto | WebSocketURL"), desc => ?T("A WebSocket URL to which Converse can connect to. " - "The keyword '@HOST@' is replaced with the real virtual " + "The '@HOST@' keyword is replaced with the real virtual " "host name. " "If set to 'auto', it will build the URL of the first " "configured WebSocket request handler. " diff --git a/src/mod_delegation.erl b/src/mod_delegation.erl index c47ebb9a5..12e2fcd50 100644 --- a/src/mod_delegation.erl +++ b/src/mod_delegation.erl @@ -117,7 +117,7 @@ mod_doc() -> [{?T("Make sure you do not delegate the same namespace to several " "services at the same time. As in the example provided later, " "to have the 'sat-pubsub.example.org' component perform " - "correctly disable the 'mod_pubsub' module."), + "correctly disable the _`mod_pubsub`_ module."), ["access_rules:", " external_pubsub:", " allow: external_component", diff --git a/src/mod_host_meta.erl b/src/mod_host_meta.erl index 1b49b6b14..80b4dbe84 100644 --- a/src/mod_host_meta.erl +++ b/src/mod_host_meta.erl @@ -214,7 +214,8 @@ mod_doc() -> ?T("To use this module, in addition to adding it to the 'modules' " "section, you must also enable it in 'listen' -> 'ejabberd_http' -> " "_`listen-options.md#request_handlers|request_handlers`_."), "", - ?T("Notice it only works if ejabberd_http has tls enabled.")], + ?T("Notice it only works if _`listen.md#ejabberd_http|ejabberd_http`_ " + "has _`listen-options.md#tls|tls`_ enabled.")], note => "added in 22.05", example => ["listen:", diff --git a/src/mod_http_api.erl b/src/mod_http_api.erl index 0ad9cfbe0..44eae9733 100644 --- a/src/mod_http_api.erl +++ b/src/mod_http_api.erl @@ -561,10 +561,10 @@ mod_doc() -> "section, you must also enable it in 'listen' -> 'ejabberd_http' -> " "_`listen-options.md#request_handlers|request_handlers`_."), "", ?T("To use a specific API version N, when defining the URL path " - "in the request_handlers, add a 'vN'. " - "For example: '/api/v2: mod_http_api'"), "", + "in the request_handlers, add a vN. " + "For example: '/api/v2: mod_http_api'."), "", ?T("To run a command, send a POST request to the corresponding " - "URL: 'http://localhost:5280/api/'")], + "URL: 'http://localhost:5280/api/COMMAND-NAME'")], example => ["listen:", " -", diff --git a/src/mod_http_upload.erl b/src/mod_http_upload.erl index dcb619c03..1b67a518b 100644 --- a/src/mod_http_upload.erl +++ b/src/mod_http_upload.erl @@ -243,14 +243,14 @@ mod_doc() -> desc => ?T("This option defines the Jabber IDs of the service. " "If the 'hosts' option is not specified, the only Jabber ID will " - "be the hostname of the virtual host with the prefix \"upload.\". " + "be the hostname of the virtual host with the prefix '\"upload.\"'. " "The keyword '@HOST@' is replaced with the real virtual host name.")}}, {name, #{value => ?T("Name"), desc => ?T("A name of the service in the Service Discovery. " - "This will only be displayed by special XMPP clients. " - "The default value is \"HTTP File Upload\".")}}, + "The default value is '\"HTTP File Upload\"'. " + "Please note this will only be displayed by some XMPP clients.")}}, {access, #{value => ?T("AccessName"), desc => @@ -270,7 +270,7 @@ mod_doc() -> desc => ?T("This option defines the length of the random " "string included in the GET and PUT URLs generated " - "by 'mod_http_upload'. The minimum length is 8 characters, " + "by 'mod_http_upload'. The minimum length is '8' characters, " "but it is recommended to choose a larger value. " "The default value is '40'.")}}, {jid_in_url, @@ -293,8 +293,8 @@ mod_doc() -> #{value => ?T("Permission"), desc => ?T("This option defines the permission bits of uploaded files. " - "The bits are specified as an octal number (see the chmod(1) " - "manual page) within double quotes. For example: \"0644\". " + "The bits are specified as an octal number (see the 'chmod(1)' " + "manual page) within double quotes. For example: '\"0644\"'. " "The default is undefined, which means no explicit permissions " "will be set.")}}, {dir_mode, @@ -302,8 +302,8 @@ mod_doc() -> desc => ?T("This option defines the permission bits of the 'docroot' " "directory and any directories created during file uploads. " - "The bits are specified as an octal number (see the chmod(1) " - "manual page) within double quotes. For example: \"0755\". " + "The bits are specified as an octal number (see the 'chmod(1)' " + "manual page) within double quotes. For example: '\"0755\"'. " "The default is undefined, which means no explicit permissions " "will be set.")}}, {docroot, @@ -311,26 +311,26 @@ mod_doc() -> desc => ?T("Uploaded files are stored below the directory specified " "(as an absolute path) with this option. The keyword " - "@HOME@ is replaced with the home directory of the user " - "running ejabberd, and the keyword @HOST@ with the virtual " - "host name. The default value is \"@HOME@/upload\".")}}, + "'@HOME@' is replaced with the home directory of the user " + "running ejabberd, and the keyword '@HOST@' with the virtual " + "host name. The default value is '\"@HOME@/upload\"'.")}}, {put_url, #{value => ?T("URL"), desc => ?T("This option specifies the initial part of the PUT URLs " - "used for file uploads. The keyword @HOST@ is replaced " + "used for file uploads. The keyword '@HOST@' is replaced " "with the virtual host name. NOTE: different virtual " "hosts cannot use the same PUT URL. " - "The default value is \"https://@HOST@:5443/upload\".")}}, + "The default value is '\"https://@HOST@:5443/upload\"'.")}}, {get_url, #{value => ?T("URL"), desc => ?T("This option specifies the initial part of the GET URLs " "used for downloading the files. The default value is 'undefined'. " "When this option is 'undefined', this option is set " - "to the same value as 'put_url'. The keyword @HOST@ is " + "to the same value as 'put_url'. The keyword '@HOST@' is " "replaced with the virtual host name. NOTE: if GET requests " - "are handled by 'mod_http_upload', the 'get_url' must match the " + "are handled by this module, the 'get_url' must match the " "'put_url'. Setting it to a different value only makes " "sense if an external web server or _`mod_http_fileserver`_ " "is used to serve the uploaded files.")}}, @@ -349,9 +349,9 @@ mod_doc() -> "Upload processing to a separate HTTP server. " "Both ejabberd and the HTTP server should share this " "secret and behave exactly as described at " - "https://modules.prosody.im/mod_http_upload_external.html" - "[Prosody's mod_http_upload_external] in the " - "'Implementation' section. There is no default value.")}}, + "https://modules.prosody.im/mod_http_upload_external.html#implementation" + "[Prosody's mod_http_upload_external: Implementation]. " + "There is no default value.")}}, {rm_on_unregister, #{value => "true | false", desc => diff --git a/src/mod_http_upload_quota.erl b/src/mod_http_upload_quota.erl index 3935588f7..4e522a83b 100644 --- a/src/mod_http_upload_quota.erl +++ b/src/mod_http_upload_quota.erl @@ -96,7 +96,7 @@ mod_options(_) -> mod_doc() -> #{desc => [?T("This module adds quota support for mod_http_upload."), "", - ?T("This module depends on 'mod_http_upload'.")], + ?T("This module depends on _`mod_http_upload`_.")], opts => [{max_days, #{value => ?T("Days"), @@ -126,10 +126,10 @@ mod_doc() -> "user may upload. When this threshold is exceeded, " "ejabberd deletes the oldest files uploaded by that " "user until their disk usage equals or falls below " - "the specified soft quota (see 'access_soft_quota'). " + "the specified soft quota (see also option 'access_soft_quota'). " "The default value is 'hard_upload_quota'.")}}], example => - [{?T("Please note that it's not necessary to specify the " + [{?T("Notice it's not necessary to specify the " "'access_hard_quota' and 'access_soft_quota' options in order " "to use the quota feature. You can stick to the default names " "and just specify access rules such as those in this example:"), diff --git a/src/mod_mix.erl b/src/mod_mix.erl index 6ef5f885b..c6aa60ef6 100644 --- a/src/mod_mix.erl +++ b/src/mod_mix.erl @@ -122,7 +122,7 @@ mod_doc() -> desc => ?T("This option defines the Jabber IDs of the service. " "If the 'hosts' option is not specified, the only Jabber ID will " - "be the hostname of the virtual host with the prefix \"mix.\". " + "be the hostname of the virtual host with the prefix '\"mix.\"'. " "The keyword '@HOST@' is replaced with the real virtual host name.")}}, {name, #{value => ?T("Name"), diff --git a/src/mod_mix_pam.erl b/src/mod_mix_pam.erl index f043393ba..afc63b8d3 100644 --- a/src/mod_mix_pam.erl +++ b/src/mod_mix_pam.erl @@ -128,7 +128,7 @@ mod_doc() -> "The module is needed if MIX compatible clients " "on your server are going to join MIX channels " "(either on your server or on any remote servers)."), "", - ?T("NOTE: 'mod_mix' is not required for this module " + ?T("NOTE: _`mod_mix`_ is not required for this module " "to work, however, without 'mod_mix_pam' the MIX " "functionality of your local XMPP clients will be impaired.")], opts => diff --git a/src/mod_mqtt_bridge.erl b/src/mod_mqtt_bridge.erl index 94930049c..2842d18ef 100644 --- a/src/mod_mqtt_bridge.erl +++ b/src/mod_mqtt_bridge.erl @@ -179,24 +179,35 @@ mod_doc() -> example => ["modules:", " mod_mqtt_bridge:", + " replication_user: \"mqtt@xmpp.server.com\"", " servers:", " \"mqtt://server.com\":", + " authentication:", + " certfile: \"/etc/ejabberd/mqtt_server.pem\"", " publish:", " \"localA\": \"remoteA\" # local changes to 'localA' will be replicated on remote server as 'remoteA'", " \"topicB\": \"topicB\"", " subscribe:", - " \"remoteB\": \"localB\" # changes to 'remoteB' on remote server will be stored as 'localB' on local server", - " authentication:", - " certfile: \"/etc/ejabberd/mqtt_server.pem\"", - " replication_user: \"mqtt@xmpp.server.com\""], + " \"remoteB\": \"localB\" # changes to 'remoteB' on remote server will be stored as 'localB' on local server"], opts => [{servers, - #{value => "{ServerUrl: {publish: [TopicPairs], subscribe: [TopicPairs], authentication: [AuthInfo]}}", + #{value => "{ServerUrl: {Key: Value}}", desc => - ?T("Declaration of data to share, must contain 'publish' or 'subscribe' or both, and 'authentication' " - "section with username/password field or certfile pointing to client certificate. " - "Accepted urls can use schema mqtt, mqtts (mqtt with tls), mqtt5, mqtt5s (both to trigger v5 protocol), " - "ws, wss, ws5, wss5. Certificate authentication can be only used with mqtts, mqtt5s, wss, wss5.")}}, + ?T("Declaration of data to share for each ServerUrl. " + "Server URLs can use schemas: 'mqtt', 'mqtts' (mqtt with tls), 'mqtt5', " + "'mqtt5s' (both to trigger v5 protocol), 'ws', 'wss', 'ws5', 'wss5'. " + "Keys must be:")}, + [{authentication, + #{value => "{AuthKey: AuthValue}", + desc => ?T("List of authentication information, where AuthKey can be: " + "'username' and 'password' fields, or 'certfile' pointing to client certificate. " + "Certificate authentication can be used only with mqtts, mqtt5s, wss, wss5.")}}, + {publish, + #{value => "{LocalTopic: RemoteTopic}", + desc => ?T("Either publish or subscribe must be set, or both.")}}, + {subscribe, + #{value => "{RemoteTopic: LocalTopic}", + desc => ?T("Either publish or subscribe must be set, or both.")}}]}, {replication_user, #{value => "JID", desc => diff --git a/src/mod_muc.erl b/src/mod_muc.erl index cee28918d..74e62dedc 100644 --- a/src/mod_muc.erl +++ b/src/mod_muc.erl @@ -1497,12 +1497,12 @@ mod_doc() -> ?T("A small history of the current discussion is sent to users " "when they enter the room. With this option you can define the " "number of history messages to keep and send to users joining the room. " - "The value is a non-negative integer. Setting the value to 0 disables " + "The value is a non-negative integer. Setting the value to '0' disables " "the history feature and, as a result, nothing is kept in memory. " - "The default value is 20. This value affects all rooms on the service. " + "The default value is '20'. This value affects all rooms on the service. " "NOTE: modern XMPP clients rely on Message Archives (XEP-0313), so feel " "free to disable the history feature if you're only using modern clients " - "and have 'mod_mam' module loaded.")}}, + "and have _`mod_mam`_ module loaded.")}}, {host, #{desc => ?T("Deprecated. Use 'hosts' instead.")}}, {hosts, #{value => ?T("[Host, ...]"), @@ -1593,7 +1593,7 @@ mod_doc() -> "When this option is not defined, message rate is not limited. " "This feature can be used to protect a MUC service from occupant " "abuses and limit number of messages that will be broadcasted by " - "the service. A good value for this minimum message interval is 0.4 second. " + "the service. A good value for this minimum message interval is '0.4' second. " "If an occupant tries to send messages faster, an error is send back " "explaining that the message has been discarded and describing the " "reason why the message is not acceptable.")}}, @@ -1610,7 +1610,7 @@ mod_doc() -> "the presence is cached by ejabberd and only the last presence " "is broadcasted to all occupants in the room after expiration " "of the interval delay. Intermediate presence packets are " - "silently discarded. A good value for this option is 4 seconds.")}}, + "silently discarded. A good value for this option is '4' seconds.")}}, {queue_type, #{value => "ram | file", desc => @@ -1843,7 +1843,7 @@ mod_doc() -> ?T("Maximum number of occupants in the room. " "The default value is '200'.")}}, {presence_broadcast, - #{value => "[moderator | participant | visitor, ...]", + #{value => "[Role]", desc => ?T("List of roles for which presence is broadcasted. " "The list can contain one or several of: 'moderator', " diff --git a/src/mod_muc_admin.erl b/src/mod_muc_admin.erl index f8cb3bd0e..dfc4fb182 100644 --- a/src/mod_muc_admin.erl +++ b/src/mod_muc_admin.erl @@ -2096,5 +2096,5 @@ mod_doc() -> note => "added in 22.05", desc => ?T("How many users can be subscribed to a room at once using " - "the 'subscribe_room_many' command. " + "the _`subscribe_room_many`_ API. " "The default value is '50'.")}}]}. diff --git a/src/mod_offline.erl b/src/mod_offline.erl index 96b541c59..abb209b77 100644 --- a/src/mod_offline.erl +++ b/src/mod_offline.erl @@ -1184,10 +1184,8 @@ mod_doc() -> "again. Thus it is very similar to how email works. A user " "is considered offline if no session presence priority > 0 " "are currently open."), "", - ?T("NOTE: 'ejabberdctl' has a command to " - "delete expired messages (see chapter " - "_`../guide/managing.md|Managing an ejabberd server`_ " - "in online documentation.")], + ?T("The _`delete_expired_messages`_ API allows to delete expired messages, " + "and _`delete_old_messages`_ API deletes older ones.")], opts => [{access_max_user_messages, #{value => ?T("AccessName"), @@ -1196,16 +1194,16 @@ mod_doc() -> "enforced to limit the maximum number of offline " "messages that a user can have (quota). When a user " "has too many offline messages, any new messages that " - "they receive are discarded, and a " + "they receive are discarded, and a '' " "error is returned to the sender. The default value is " "'max_user_offline_messages'.")}}, {store_empty_body, #{value => "true | false | unless_chat_state", desc => - ?T("Whether or not to store messages that lack a " + ?T("Whether or not to store messages that lack a '' " "element. The default value is 'unless_chat_state', " "which tells ejabberd to store messages even if they " - "lack the element, unless they only contain a " + "lack the '' element, unless they only contain a " "chat state notification (as defined in " "https://xmpp.org/extensions/xep-0085.html" "[XEP-0085: Chat State Notifications].")}}, @@ -1217,8 +1215,8 @@ mod_doc() -> {use_mam_for_storage, #{value => "true | false", desc => - ?T("This is an experimental option. Enabling this option, " - "'mod_offline' uses the 'mod_mam' archive table instead " + ?T("This is an experimental option. By enabling the option, " + "this module uses the 'archive' table from _`mod_mam`_ instead " "of its own spool table to retrieve the messages received " "when the user was offline. This allows client " "developers to slowly drop XEP-0160 and rely on XEP-0313 " diff --git a/src/mod_privacy.erl b/src/mod_privacy.erl index 0a7911e26..b52000762 100644 --- a/src/mod_privacy.erl +++ b/src/mod_privacy.erl @@ -895,8 +895,8 @@ mod_doc() -> ?T("NOTE: Nowadays modern XMPP clients rely on " "https://xmpp.org/extensions/xep-0191.html" "[XEP-0191: Blocking Command] which is implemented by " - "'mod_blocking' module. However, you still need " - "'mod_privacy' loaded in order for _`mod_blocking`_ to work.")], + "_`mod_blocking`_. However, you still need " + "'mod_privacy' loaded in order for 'mod_blocking' to work.")], opts => [{db_type, #{value => "mnesia | sql", diff --git a/src/mod_private.erl b/src/mod_private.erl index e3bc72593..2dea64c45 100644 --- a/src/mod_private.erl +++ b/src/mod_private.erl @@ -135,7 +135,7 @@ mod_doc() -> "[XEP-0048: Bookmarks])."), "", ?T("It also implements the bookmark conversion described in " "https://xmpp.org/extensions/xep-0402.html[XEP-0402: PEP Native Bookmarks]" - ", see the command _`bookmarks_to_pep`_ API.")], + ", see _`bookmarks_to_pep`_ API.")], opts => [{db_type, #{value => "mnesia | sql", diff --git a/src/mod_shared_roster.erl b/src/mod_shared_roster.erl index 39c563dfb..c0c8c4b49 100644 --- a/src/mod_shared_roster.erl +++ b/src/mod_shared_roster.erl @@ -1343,7 +1343,7 @@ mod_doc() -> "contacts are merged to the relevant users at retrieval time. " "The standard user rosters thus stay unmodified."), "", ?T("Shared roster groups can be edited via the Web Admin, " - "and some API commands called 'srg_*'. " + "and some API commands called 'srg_', for example _`srg_add`_ API. " "Each group has a unique name and those parameters:"), "", ?T("- Label: Used in the rosters where this group is displayed."),"", ?T("- Description: of the group, which has no effect."), "",