Add mod_pubsub configuration documentation

1 files changed, 202 insertions, 1 deletions

diff --git a/src/mod_pubsub.erl b/src/mod_pubsub.erl
index 7653d41e2..62e71008e 100644
--- a/src/mod_pubsub.erl
+++ b/src/mod_pubsub.erl
@@ -90,7 +90,7 @@
 
 %% API and gen_server callbacks
 -export([start/2, stop/1, init/1,
-    handle_call/3, handle_cast/2, handle_info/2,
+    handle_call/3, handle_cast/2, handle_info/2, mod_doc/0,
     terminate/2, code_change/3, depends/2, mod_opt_type/1, mod_options/1]).
 
 -export([route/1]).
@@ -4180,3 +4180,204 @@ mod_options(Host) ->
      {max_subscriptions_node, undefined},
      {default_node_config, []},
      {force_node_config, []}].
+
+mod_doc() ->
+    #{desc =>
+	  [?T("This module offers a service for "
+	      "https://xmpp.org/extensions/xep-0060.html"
+	      "[XEP-0060: Publish-Subscribe]. The functionality in "
+	      "'mod_pubsub' can be extended using plugins. "
+	      "The plugin that implements PEP "
+	      "(https://xmpp.org/extensions/xep-0163.html"
+	      "[XEP-0163: Personal Eventing via Pubsub]) "
+	      "is enabled in the default ejabberd configuration file, "
+	      "and it requires 'mod_caps'.")],
+      opts =>
+          [{max_nodes_discoitems,
+            #{value => "pos_integer() | infinity",
+              desc => ?T("The maximum number of nodes to return in a "
+			 "discoitem response. The default value is: '100'.")}},
+           {access_createnode,
+            #{value => "AccessName",
+              desc => ?T("This option restricts which users are allowed to "
+			 "create pubsub nodes using 'acl' and 'access'. "
+			 "By default any account in the local ejabberd server "
+			 "is allowed to create pubsub nodes. "
+			 "The default value is: 'all'.")}},
+           {max_items_node,
+            #{value => "MaxItems",
+              desc => ?T("Define the maximum number of items that can be "
+			 "stored in a node. Default value is: '10'.")}},
+           {max_subscriptions_node,
+            #{value => "MaxSubs",
+              desc => ?T("Define the maximum number of subscriptions managed "
+			 "by a node. "
+			 "Default value is no limitation: 'undefined'.")}},
+           {plugins,
+            #{value => "[Plugin, ...]",
+              desc => [?T("To specify which pubsub node plugins to use. "
+			  "The first one in the list is used by default. "
+			  "If this option is not defined, the default plugins "
+			  "list is: '[flat]'. PubSub clients can define which "
+			  "plugin to use when creating a node: "
+			  "add 'type=\'plugin-name\'' attribute "
+			  "to the 'create' stanza element."),
+		       ?T("- 'flat' plugin handles the default behaviour and "
+			  "follows standard XEP-0060 implementation."),
+		       ?T("- 'pep' plugin adds extention to handle Personal "
+			  "Eventing Protocol (XEP-0163) to the PubSub engine. "
+			  "Adding pep allows to handle PEP automatically.")]}},
+	   {nodetree,
+            #{value => "Nodetree",
+              desc =>
+		  [?T("To specify which nodetree to use. If not defined, the "
+		      "default pubsub nodetree is used: 'tree'. Only one "
+		      "nodetree can be used per host, and is shared by all "
+		      "node plugins."),
+		   ?T("- 'tree' nodetree store node configuration and "
+		      "relations on the database. 'flat' nodes are stored "
+		      "without any relationship, and 'hometree' nodes can "
+		      "have child nodes."),
+		   ?T("- 'virtual' nodetree does not store nodes on database. "
+		      "This saves resources on systems with tons of nodes. "
+		      "If using the 'virtual' nodetree, you can only enable "
+		      "those node plugins: '[flat, pep]' or '[flat]'; any "
+		      "other plugins configuration will not work. Also, all "
+		      "nodes will have the default configuration, and this "
+		      "can not be changed. Using 'virtual' nodetree requires "
+		      "to start from a clean database, it will not work if "
+		      "you used the default 'tree' nodetree before."),
+		   ?T("- 'dag' nodetree provides experimental support for "
+		      "PubSub Collection Nodes (XEP-0248). In that case you "
+		      "should also add 'dag' node plugin as default, for "
+		      "example: 'plugins: [flat,pep]'")]}},
+	   {ignore_pep_from_offline,
+            #{value => "false | true",
+              desc => ?T("To specify whether or not we should get last "
+			 "published PEP items from users in our roster which "
+			 "are offline when we connect. Value is 'true' or "
+			 "'false'. If not defined, pubsub assumes true so we "
+			 "only get last items of online contacts.")}},
+           {last_item_cache,
+            #{value => "false | true",
+              desc => ?T("To specify whether or not pubsub should cache last "
+			 "items. Value is 'true' or 'false'. If not defined, "
+			 "pubsub does not cache last items. On systems with not"
+			 " so many nodes, caching last items speeds up pubsub "
+			 "and allows to raise user connection rate. The cost "
+			 "is memory usage, as every item is stored in memory.")}},
+           {force_node_config,
+            #{value => "List of Node and the list of its Key:Value",
+              desc => ?T("Define the configuration for given nodes. "
+			 "The default value is: '[]'."),
+              example =>
+		  ["force_node_config:",
+		   "  ## Avoid buggy clients to make their bookmarks public",
+		   "  storage:bookmarks:",
+		   "    access_model: whitelist"]}},
+           {default_node_config,
+            #{value => "List of Key:Value",
+              desc => ?T("To override default node configuration, regardless "
+			 "of node plugin. Value is a list of key-value "
+			 "definition. Node configuration still uses default "
+			 "configuration defined by node plugin, and overrides "
+			 "any items by value defined in this configurable list.
+")}},
+           {pep_mapping,
+            #{value => "List of Key:Value",
+              desc => ?T("This allows to define a list of key-value to choose "
+			 "defined node plugins on given PEP namespace."),
+              example =>
+		  [{?T("The following example will use 'node_tune' instead of "
+		       "'node_pep' for every PEP node with the tune namespace:"),
+		    ["modules:",
+		     "  ...",
+		     "  mod_pubsub:",
+		     "    pep_mapping:",
+		     "      http://jabber.org/protocol/tune: tune",
+		     "  ..."]
+		   }]}},
+	   {db_type,
+	    #{value => "mnesia | sql",
+	      desc =>
+		  ?T("Same as top-level 'default_db' option, but applied to "
+		     "this module only.")}},
+	   {host,
+	    #{desc => ?T("Deprecated. Use 'hosts' instead.")}},
+	   {hosts,
+	    #{value => ?T("[Host, ...]"),
+	      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 \"vjud.\". The keyword '@HOST@' is replaced with "
+		     "the real virtual host name.")}},
+	   {name,
+	    #{value => ?T("Name"),
+	      desc =>
+		  ?T("The value of the service name. This name is only visible "
+		     "in some clients that support "
+		     "https://xmpp.org/extensions/xep-0030.html"
+		     "[XEP-0030: Service Discovery]. "
+		     "The default is 'vCard User Search'.")}},
+	   {vcard,
+	    #{value => ?T("vCard"),
+	      desc =>
+		  ?T("A custom vCard of the server that will be displayed by "
+		     "some XMPP clients in Service Discovery. The value of "
+		     "'vCard' is a YAML map constructed from an XML "
+		     "representation of vCard. Since the representation has "
+		     "no attributes, the mapping is straightforward."),
+	      example =>
+		  [{?T("The following XML representation of vCard:"),
+		    ["<vCard xmlns='vcard-temp'>",
+		     "  <FN>PubSub Service</FN>",
+		     "  <ADR>",
+		     "    <WORK/>",
+		     "    <STREET>Elm Street</STREET>",
+		     "  </ADR>",
+		     "</vCard>"]},
+		   {?T("will be translated to:"),
+		    ["vcard:",
+		     "  fn: PubSub Service",
+		     "  adr:",
+		     "    -",
+		     "      work: true",
+		     "      street: Elm Street"]}]}}
+	  ],
+      example =>
+	  [{?T("Example of configuration that uses flat nodes as default, "
+	       "and allows use of flat, hometree and pep nodes:"),
+	    [
+	     "modules:",
+	     "  ...",
+	     "  mod_pubsub:",
+	     "    access_createnode: pubsub_createnode",
+	     "    max_subscriptions_node: 100",
+	     "    default_node_config:",
+	     "      notification_type: normal",
+	     "      notify_retract: false",
+	     "      max_items: 4",
+	     "    plugins:",
+	     "      - flat",
+	     "      - pep",
+	     "  ..."
+	    ]},
+	   {?T("Using relational database requires using mod_pubsub with "
+	       "db_type 'sql'. Only flat, hometree and pep plugins supports "
+	       "SQL. The following example shows previous configuration "
+	       "with SQL usage:"),
+	    [
+	     "modules:",
+	     "  ...",
+	     "  mod_pubsub:",
+	     "    db_type: sql",
+	     "    access_createnode: pubsub_createnode",
+	     "    ignore_pep_from_offline: true",
+	     "    last_item_cache: false",
+	     "    plugins:",
+	     "      - flat",
+	     "      - pep",
+	     "  ..."
+	    ]}
+	  ]}.