RosterManager: Document handling of Moved old JIDs

The handling of moved old JIDs and interaction with the
QXmppMovedManager was undocumented. This adds documentation, including
the behaviour changes between 1.9.4/1.10.1 and 1.9.5/1.10.2.

Author: lnjX

src/client/QXmppRosterManager.cpp

@@ -74,11 +74,16 @@ static void serializeRosterData(const RosterData &d, QXmlStreamWriter &writer)
 /// The user can either accept the request by calling acceptSubscription() or refuse it
 /// by calling refuseSubscription().
 ///
+/// Since *QXmpp 1.10.2* only verified \xep{0283, Moved} old JIDs are passed in \a presence. If
+/// verification fails or the given old JID is not valid, the attribute is cleared in the
+/// QXmppPresence. See \ref rostermanager_moved "above" for more details.
+///
 /// \note If QXmppConfiguration::autoAcceptSubscriptions() is set to true or the subscription
 /// request is automatically accepted by the QXmppMovedManager, this signal will not be emitted.
 ///
 /// \param subscriberBareJid bare JID that wants to subscribe to the user's presence
-/// \param presence presence stanza containing the reason / message (presence.statusText())
+/// \param presence presence stanza, e.g. containing the message (presence.statusText()),
+/// \xep{0283, Moved} old JID or other information
 ///
 /// \since QXmpp 1.5
 ///

src/client/QXmppRosterManager.h

@@ -51,6 +51,33 @@ class QXmppRosterManagerPrivate;
 /// The \c presenceChanged() signal is emitted whenever the presence for a
 /// roster item changes.
 ///
+/// \anchor rostermanager_moved
+/// ## XEP-0283: Moved
+///
+/// \xep{0283, Moved} provides a way to inform other users that an account has moved. This allows a
+/// presence subscription request from a new account to be automatically linked to the old account.
+/// However, this requires verification via a corresponding PubSub node on the old account.
+///
+/// The roster manager automatically checks entries using the QXmppMovedManager. For this to work,
+/// the moved manager must be added to the QXmppClient. If the moved manager is not found or the
+/// specified old JID is incorrect, the entry in the presence subscription request will be removed.
+///
+/// The received and verified presence subscription request is emitted via
+/// subscriptionRequestReceived() and the old JID can be found in QXmppPresence::oldJid().
+/// It is safe to assume that this old JID is valid since QXmpp 1.10.2.
+///
+/// Accepting moved subscription requests automatically is discouraged in
+/// [section 4.3](https://xmpp.org/extensions/xep-0283.html#receive-notification-client) of the
+/// XEP.
+///
+/// ### Behaviour in previous versions
+///
+/// Support in the roster manager and in QXmppPresence was initially added in 1.9.0.
+///
+/// In QXmpp 1.9.0 until 1.9.4 and 1.10.0 until 1.10.1 subscription requests with a Moved element
+/// are verified and automatically accepted without emitting subscriptionRequestReceived(). If
+/// verification fails, the **invalid** old JID is passed in subscriptionRequestReceived()!
+///
 /// \ingroup Managers
 ///
 class QXMPP_EXPORT QXmppRosterManager : public QXmppClientExtension