# HG changeset patch
# User Goffi <goffi@goffi.org>
# Date 1647964842 -3600
# Node ID fa3dc4ed7906cc3138eeda66250106c30e228e2e
# Parent  a8c7e5cef0cba0b19f38032b7489e57229e5d5a3
doc (components): documentation of `comments_max_depth` option and threads conversion:

ActivityPub to XMPP threads conversion is detailed.

fix 364

diff -r a8c7e5cef0cb -r fa3dc4ed7906 doc/components.rst
--- a/doc/components.rst	Tue Mar 22 17:00:42 2022 +0100
+++ b/doc/components.rst	Tue Mar 22 17:00:42 2022 +0100
@@ -233,6 +233,10 @@
 
   **default**: ``_ap``
 
+``comments_max_depth``
+  An integer value indicating the maximum number of comment nodes that can be created. See
+  :ref:`ap-xmpp-threads-conversion`
+
 
 .. _ap-actor-from-xmpp:
 
@@ -361,6 +365,52 @@
    before your entity is followed. Other implementations may work differently.
 
 
+.. _ap-xmpp-threads-conversion:
+
+ActivyPub to XMPP Discussion Threads Conversion
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+By default, each (micro)blog publication converted from ActivityPub to XMPP Pubsub is
+associated with a comment node (see `XEP-0277 comments`_) to allow user to post a reply on
+any on them. This result in a "tree-like" comments threading model, which is similar to
+what you can see on popular website such as Reddit, Hacker News, or LinuxFr.
+
+However, some XMPP clients may not play nicely with this kind of threading model. To work
+around this, the ``comments_max_depth`` option allows to limit the maximum number of
+thread. It is an integer value which indicate how many comments nodes may exist for a root
+post. If set to ``1``, only one comment node will be made, and ActivityPub items below
+this level will be moved to this single XMPP pubsub comment node.
+
+The default value of ``0`` means unlimited max depth.
+
+An example can probably make it more clear. Imagine that you have a message ``root
+message``, with a comment to it named ``1``, a comment to ``1`` named ``2`` and so on
+until ``5``. With ``comments_max_depth`` set to ``0``, you'll have one comment node per
+item, resulting in following threads model::
+
+  root message ┑
+               ┕ 1 ┑
+                   ┕ 2 ┑
+                       ┕ 3 ┑
+                           ┕ 4 ┑
+                               ┕ 5
+
+With ``comments_max_depth`` set to ``2``, only 2 nodes will be created, and items below
+depth ``2`` will be put on the same level::
+
+  root message ┑
+               ┕ 1 ┑
+                   ┝ 2
+                   ┝ 3
+                   ┝ 4
+                   ┕ 5
+
+This way, admins can configure the model which suits best the clients which is expected to
+be mainly used on the instance.
+
+.. _XEP-0277 comments: https://xmpp.org/extensions/xep-0277.html#comments
+
+
 Using the Component (for developers)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~