Copy more option explanations from ejabberd Docs site

12 files changed, 122 insertions, 39 deletions

diff --git a/src/ejabberd_options_doc.erl b/src/ejabberd_options_doc.erl
index 2d201a471..5494cc12c 100644
--- a/src/ejabberd_options_doc.erl
+++ b/src/ejabberd_options_doc.erl
@@ -60,32 +60,49 @@ doc() ->
       #{value => "timeout()",
         desc =>
             ?T("The time of a cached item to keep in cache. "
-               "Once it's expired, the corresponding item is "
-               "erased from cache. The default value is 'one hour'.")}},
+	       "Once it's expired, the corresponding item is "
+	       "erased from cache. The default value is 'one hour'. "
+	       "Several modules have a similar option; and some core "
+	       "ejabberd parts support similar options too, see "
+	       "'auth_cache_life_time', 'oauth_cache_life_time', "
+	       "'router_cache_life_time', and 'sm_cache_life_time'.")}},
      {cache_missed,
       #{value => "true | false",
         desc =>
             ?T("Whether or not to cache missed lookups. When there is "
-               "an attempt to lookup for a value in a database and "
-               "this value is not found and the option is set to 'true', "
-               "this attempt will be cached and no attempts will be "
-               "performed until the cache expires (see 'cache_life_time'). "
-               "Usually you don't want to change it. Default is 'true'.")}},
+	       "an attempt to lookup for a value in a database and "
+	       "this value is not found and the option is set to 'true', "
+	       "this attempt will be cached and no attempts will be "
+	       "performed until the cache expires (see 'cache_life_time'). "
+	       "Usually you don't want to change it. Default is 'true'. "
+	       "Several modules have a similar option; and some core "
+	       "ejabberd parts support similar options too, see "
+	       "'auth_cache_missed', 'oauth_cache_missed', "
+	       "'router_cache_missed', and 'sm_cache_missed'.")}},
      {cache_size,
       #{value => "pos_integer() | infinity",
         desc =>
-            ?T("A maximum number of items (not memory!) in cache. "
-               "The rule of thumb, for all tables except rosters, "
-               "you should set it to the number of maximum online "
-               "users you expect. For roster multiply this number "
-               "by 20 or so. If the cache size reaches this threshold, "
-               "it's fully cleared, i.e. all items are deleted, and "
-               "the corresponding warning is logged. You should avoid "
-               "frequent cache clearance, because this degrades "
-               "performance. The default value is '1000'.")}},
+	    ?T("A maximum number of items (not memory!) in cache. "
+	       "The rule of thumb, for all tables except rosters, "
+	       "you should set it to the number of maximum online "
+	       "users you expect. For roster multiply this number "
+	       "by 20 or so. If the cache size reaches this threshold, "
+	       "it's fully cleared, i.e. all items are deleted, and "
+	       "the corresponding warning is logged. You should avoid "
+	       "frequent cache clearance, because this degrades "
+	       "performance. The default value is '1000'. "
+	       "Several modules have a similar option; and some core "
+	       "ejabberd parts support similar options too, see "
+	       "'auth_cache_size', 'oauth_cache_size', "
+	       "'router_cache_size', and 'sm_cache_size'.")}},
      {use_cache,
       #{value => "true | false",
-        desc => ?T("Enable or disable cache. The default is 'true'.")}},
+        desc =>
+	    ?T("Enable or disable cache. The default is 'true'. "
+	       "Several modules have a similar option; and some core "
+	       "ejabberd parts support similar options too, see "
+	       "'auth_use_cache', 'oauth_use_cache', 'router_use_cache', "
+	       "and 'sm_use_cache'.")}},
      {default_db,
       #{value => "mnesia | sql",
         desc =>
diff --git a/src/mod_announce.erl b/src/mod_announce.erl
index cc4d20c83..a0bfa180b 100644
--- a/src/mod_announce.erl
+++ b/src/mod_announce.erl
@@ -925,6 +925,10 @@ mod_doc() ->
               "Configured users can perform these actions with an XMPP "
               "client either using Ad-hoc Commands or sending messages "
               "to specific JIDs."), "",
+	   ?T("Note that this module can be resource intensive on large "
+	      "deployments as it may broadcast a lot of messages. This module "
+	      "should be disabled for instances of ejabberd with hundreds of "
+	      "thousands users."), "",
            ?T("The Ad-hoc Commands are listed in the Server Discovery. "
               "For this feature to work, 'mod_adhoc' must be enabled."), "",
            ?T("The specific JIDs where messages can be sent are listed below. "
diff --git a/src/mod_delegation.erl b/src/mod_delegation.erl
index ea0061089..da16ce89e 100644
--- a/src/mod_delegation.erl
+++ b/src/mod_delegation.erl
@@ -85,13 +85,18 @@ mod_options(_Host) ->
 
 mod_doc() ->
     #{desc =>
-          ?T("This module is an implementation of "
+          [?T("This module is an implementation of "
              "https://xmpp.org/extensions/xep-0355.html"
              "[XEP-0355: Namespace Delegation]. "
              "Only admin mode has been implemented by now. "
              "Namespace delegation allows external services to "
              "handle IQ using specific namespace. This may be applied "
-             "for external PEP service."),
+             "for external PEP service."), "",
+	   ?T("WARNING: Security issue: Namespace delegation gives components "
+	      "access to sensitive data, so permission should be granted "
+	      "carefully, only if you trust the component."), "",
+	   ?T("NOTE: This module is complementary to 'mod_privilege' but can "
+	      "also be used separately.")],
       opts =>
           [{namespaces,
             #{value => "{Namespace: Options}",
@@ -109,6 +114,10 @@ mod_doc() ->
                     ?T("The option defines which components are allowed "
                        "for namespace delegation. The default value is 'none'.")}}]}],
       example =>
+	  [{?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."),
           ["access_rules:",
            "  external_pubsub:",
            "    allow: external_component",
@@ -126,7 +135,7 @@ mod_doc() ->
            "      urn:xmpp:mam:1:",
            "        access: external_mam",
            "      http://jabber.org/protocol/pubsub:",
-           "        access: external_pubsub"]}.
+           "        access: external_pubsub"]}]}.
 
 depends(_, _) ->
     [].
diff --git a/src/mod_fail2ban.erl b/src/mod_fail2ban.erl
index b9fed0db0..48e7fb8e0 100644
--- a/src/mod_fail2ban.erl
+++ b/src/mod_fail2ban.erl
@@ -263,7 +263,13 @@ mod_doc() ->
               "record of authentication failures after some time since the "
               "first failure or on a successful authentication. "
               "It also does not simply block network traffic, but "
-              "provides the client with a descriptive error message.")],
+              "provides the client with a descriptive error message."), "",
+	   ?T("WARNING: You should not use this module behind a proxy or load "
+	      "balancer. ejabberd will see the failures as coming from the "
+	      "load balancer and, when the threshold of auth failures is "
+	      "reached, will reject all connections coming from the load "
+	      "balancer. You can lock all your user base out of ejabberd "
+	      "when using this module behind a proxy.")],
       opts =>
           [{access,
             #{value => ?T("AccessName"),
diff --git a/src/mod_http_api.erl b/src/mod_http_api.erl
index 912299e45..3a1b22034 100644
--- a/src/mod_http_api.erl
+++ b/src/mod_http_api.erl
@@ -524,5 +524,13 @@ mod_options(_) ->
 
 mod_doc() ->
     #{desc =>
-          ?T("This module provides a ReST API to call "
-             "ejabberd commands using JSON data.")}.
+	  [?T("This module provides a ReST API to call ejabberd commands "
+	      "using JSON data."), "",
+	   ?T("To use this module, in addition to adding it to the 'modules' "
+	      "section, you must also add it to 'request_handlers' of some "
+	      "listener."), "",
+	   ?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'"), "",
+	   ?T("To run a command, send a POST request to the corresponding "
+	      "URL: 'http://localhost:5280/api/<command_name>'")]}.
diff --git a/src/mod_http_upload_quota.erl b/src/mod_http_upload_quota.erl
index ed1bbe331..2fd7b5c28 100644
--- a/src/mod_http_upload_quota.erl
+++ b/src/mod_http_upload_quota.erl
@@ -130,6 +130,10 @@ mod_doc() ->
                      "the specified soft quota (see 'access_soft_quota'). "
                      "The default value is 'hard_upload_quota'.")}}],
       example =>
+	  [{?T("Please note that 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:"),
           ["shaper_rules:",
            "  ...",
            "  soft_upload_quota:",
@@ -143,7 +147,7 @@ mod_doc() ->
            "  mod_http_upload: {}",
            "  mod_http_upload_quota:",
            "    max_days: 100",
-           "  ..."]}.
+           "  ..."]}]}.
 
 -spec depends(binary(), gen_mod:opts()) -> [{module(), hard | soft}].
 depends(_Host, _Opts) ->
diff --git a/src/mod_mix.erl b/src/mod_mix.erl
index bc69c1aa1..29fa6e4ac 100644
--- a/src/mod_mix.erl
+++ b/src/mod_mix.erl
@@ -107,6 +107,10 @@ mod_doc() ->
               "yet ready to use in production. It's asserted that "
               "the MIX protocol is going to replace the MUC protocol "
               "in the future (see 'mod_muc')."), "",
+           ?T("To learn more about how to use that feature, you can refer to "
+	      "our tutorial: https://docs.ejabberd.im/tutorials/mix-010/"
+	      "[Getting started with XEP-0369: Mediated Information "
+	      "eXchange (MIX) v0.1]."), "",
            ?T("The module depends on 'mod_mam'.")],
       opts =>
           [{access_create,
diff --git a/src/mod_muc.erl b/src/mod_muc.erl
index 65f70d1d6..59ea3190a 100644
--- a/src/mod_muc.erl
+++ b/src/mod_muc.erl
@@ -1280,9 +1280,20 @@ mod_options(Host) ->
 
 mod_doc() ->
     #{desc =>
-          ?T("This module provides support for https://xmpp.org/extensions/xep-0045.html"
+          [?T("This module provides support for https://xmpp.org/extensions/xep-0045.html"
              "[XEP-0045: Multi-User Chat]. Users can discover existing rooms, "
-             "join or create them. Occupants of a room can chat in public or have private chats."),
+             "join or create them. Occupants of a room can chat in public or have private chats."), "",
+	   ?T("The MUC service allows any Jabber ID to register a nickname, so "
+	      "nobody else can use that nickname in any room in the MUC "
+	      "service. To register a nickname, open the Service Discovery in "
+	      "your XMPP client and register in the MUC service."), "",
+	   ?T("This module supports clustering and load balancing. One module "
+	      "can be started per cluster node. Rooms are distributed at "
+	      "creation time on all available MUC module instances. The "
+	      "multi-user chat module is clustered but the rooms themselves "
+	      "are not clustered nor fault-tolerant: if the node managing a "
+	      "set of rooms goes down, the rooms disappear and they will be "
+	      "recreated on an available node on first connection attempt.")],
       opts =>
           [{access,
             #{value => ?T("AccessName"),
diff --git a/src/mod_privilege.erl b/src/mod_privilege.erl
index c334348b4..1830cb5ab 100644
--- a/src/mod_privilege.erl
+++ b/src/mod_privilege.erl
@@ -100,6 +100,12 @@ mod_doc() ->
               "It is worth noting that the permissions grant access to "
               "the component to a specific data type for all users of "
               "the virtual host on which 'mod_privilege' is loaded."), "",
+	   ?T("Make sure you have a listener configured to connect your "
+	      "component. Check the section about listening ports for more "
+	      "information."), "",
+	   ?T("WARNING: Security issue: Privileged access gives components "
+	      "access to sensitive data, so permission should be granted "
+	      "carefully, only if you trust a component."), "",
            ?T("NOTE: This module is complementary to 'mod_delegation', "
               "but can also be used separately.")],
       opts =>
diff --git a/src/mod_register.erl b/src/mod_register.erl
index ac0e667ea..349113191 100644
--- a/src/mod_register.erl
+++ b/src/mod_register.erl
@@ -628,7 +628,10 @@ mod_doc() ->
               "This protocol enables end users to use a XMPP client to:"), "",
            ?T("* Register a new account on the server."), "",
            ?T("* Change the password from an existing account on the server."), "",
-           ?T("* Delete an existing account on the server.")],
+           ?T("* Delete an existing account on the server."), "",
+           ?T("This module reads also another option defined globally for the "
+	      "server: 'registration_timeout'. Please check that option "
+	      "documentation in the section with top-level options.")],
       opts =>
           [{access,
             #{value => ?T("AccessName"),
diff --git a/src/mod_register_web.erl b/src/mod_register_web.erl
index a2249430c..15eb58e75 100644
--- a/src/mod_register_web.erl
+++ b/src/mod_register_web.erl
@@ -625,5 +625,13 @@ mod_doc() ->
            ?T("- Register a new account on the server."), "",
            ?T("- Change the password from an existing account on the server."), "",
            ?T("- Delete an existing account on the server."), "",
+	   ?T("This module supports CAPTCHA image to register a new account. "
+	      "To enable this feature, configure the options 'captcha\_cmd' "
+	      "and 'captcha\_host', which are documented in the section with "
+	      "top-level options."), "",
+	   ?T("As an example usage, the users of the host 'example.org' can "
+	      "visit the page: 'https://example.org:5281/register/' It is "
+	      "important to include the last / character in the URL, "
+	      "otherwise the subpages URL will be incorrect."), "",
            ?T("The module depends on 'mod_register' where all the configuration "
               "is performed.")]}.
diff --git a/src/mod_shared_roster_ldap.erl b/src/mod_shared_roster_ldap.erl
index f8594af71..80297b41b 100644
--- a/src/mod_shared_roster_ldap.erl
+++ b/src/mod_shared_roster_ldap.erl
@@ -654,10 +654,12 @@ mod_doc() ->
            ?T("- Connection parameters: The module also accepts the "
 	      "connection parameters, all of which default to the top-level "
 	      "parameter of the same name, if unspecified. "
-	      "See 'LDAP Connection' for more information about them."), "",
-           ?T("The ejabberd Guide includes details for retrieving the roster, "
-	      "configuration examples including Flat DIT and Deep DIT, and "
-	      "also describes some of those options in more detail.")],
+	      "See http://../database-ldap/#ldap-connection[LDAP Connection] "
+	      "section for more information about them."), "",
+           ?T("Check also the http://../database-ldap/#configuration-examples"
+	      "[Configuration examples] section to get details about "
+	      "retrieving the roster, "
+	      "and configuration examples including Flat DIT and Deep DIT.")],
       opts =>
           [
 	   %% Filters:
@@ -683,12 +685,14 @@ mod_doc() ->
                   ?T("\"User Filter\", used for retrieving the human-readable "
 		     "name of roster entries (usually full names of people in "
 		     "the roster). See also the parameters 'ldap_userdesc' and "
-		     "'ldap_useruid'. For details check the ejabberd Guide.")}},
+		     "'ldap_useruid'. For more information check the LDAP "
+		     "http://../database-ldap/#filters[Filters] section.")}},
            {ldap_filter,
             #{desc =>
 		  ?T("Additional filter which is AND-ed together "
 		     "with \"User Filter\" and \"Group Filter\". "
-		     "For details please read the ejabberd Guide.")}},
+		     "For more information check the LDAP "
+		     "http://../database-ldap/#filters[Filters] section.")}},
 	   %% Attributes:
            {ldap_groupattr,
             #{desc =>
@@ -739,17 +743,16 @@ mod_doc() ->
            {ldap_memberattr_format_re,
             #{desc =>
 		  ?T("A regex for extracting user ID from the value of the "
-		     "attribute named by 'ldap_memberattr'. For details "
-		     "please read the ejabberd Guide.")}},
+		     "attribute named by 'ldap_memberattr'. Check the LDAP "
+		     "http://../database-ldap/#control-parameters"
+		     "[Control Parameters] section.")}},
            {ldap_auth_check,
             #{value => "true | false",
               desc =>
 		  ?T("Whether the module should check (via the ejabberd "
 		     "authentication subsystem) for existence of each user in "
-		     "the shared LDAP roster. See section "
-		     "'mod_shared_roster_ldap' for more information. Set to "
-		     "'false' if you want to disable the check. "
-		     "Default value is 'true'.")}}] ++
+		     "the shared LDAP roster. Set to 'false' if you want to "
+		     "disable the check. Default value is 'true'.")}}] ++
           [{Opt,
             #{desc =>
                   {?T("Same as top-level '~s' option, but "