doc: Add missing overview documentation for some backend interfaces

Add documentation for QIfPagingModelInterface and
QIfFilterAndBrowseModelInterface.

Change-Id: Idd6d258974ebc92e23b5dfbf564f7a73f866e60e
Reviewed-by: Maycon Stamboroski <maycon.stamboroski@qt.io>
Reviewed-by: Robert Griebl <robert.griebl@qt.io>
(cherry picked from commit e40d0667ccb0ee5092b242ea089aead2d180f8c8)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>
(cherry picked from commit eb550104757c6e1f30af908f6efba2b73ab27c84)

4 files changed, 110 insertions, 11 deletions

diff --git a/src/interfaceframework/qiffilterandbrowsemodelinterface.cpp b/src/interfaceframework/qiffilterandbrowsemodelinterface.cpp
index 067c4d83..b5f7cd72 100644
--- a/src/interfaceframework/qiffilterandbrowsemodelinterface.cpp
+++ b/src/interfaceframework/qiffilterandbrowsemodelinterface.cpp
@@ -18,15 +18,64 @@ QT_BEGIN_NAMESPACE
 
     The QIfFilterAndBrowseModelInterface is the interface used by \l QIfFilterAndBrowseModel
 
-    The interface is discovered by a \l QIfFilterAndBrowseModel object, which connects to it and sets it up.
+    The interface is discovered by a \l QIfFilterAndBrowseModel object, which connects to it and
+    sets it up.
 
-    Every QIfFilterAndBrowseModel generates its own QUuid which is passed to the backend interface and can
-    be used to identify a model instance.
+    Implementing QIfFilterAndBrowseModelInterface follows the same pattern as described in
+    QIfPagingModelInterface. In addition, the following features can be used by setting the
+    respective capability.
 
-    \sa QIfFilterAndBrowseModel
+    \section1 Navigation
+
+    When implementing something like a Media Library, it is useful to support navigating through
+    multiple hierarchies, for example: show all artists, select one and show all albums of that
+    artist. See also the \l {Browsing}{Browsing section of the QIfFilterAndBrowseModel}.
+
+    The \l canGoForwardChanged() and the \l canGoBackChanged() signals let the
+    QIfFilterAndBrowseModel know how it can navigate. The actual request to navigate forward or
+    backward is done using the \l goForward() and \l goBack() functions.
+
+    The \l availableContentTypesChanged() signal needs to be emitted to define which types can be
+    browsed in this backend and let the user select the starting point to browse from.
+
+    Once the user selected a content type, the \l setContentType function is called and the backend
+    needs to inform about the new contentType using the \l contentTypeChanged signal.
+
+    If the backend supports navigating without saving the state of a model instance locally, the
+    \l{ModelCapabilities}{SupportsStatelessNavigation} capability can be set.
+
+    \section1 Filtering and Sorting
 
-    //TODO explain how the interface works on a example
-    <example of a fully featured backend>
+    To support sorting and filtering of the model content on the backend side, the respective
+    capabilities need to be set: \l{ModelCapabilities}{SupportsFiltering} and
+    \l{ModelCapabilities}{SupportsSorting}
+    To also allow complex filtering, the \l{ModelCapabilities}{SupportsAndConjunction} and
+    \l{ModelCapabilities}{SupportsOrConjunction} can be set in addition.
+    See also the \l {FilteringAndSorting}{Filtering and Sorting section of the
+    QIfFilterAndBrowseModel}.
+
+    Once a content type has been set on the backend, the \l queryIdentifiersChanged() signal
+    needs to be emitted to inform the frontend about all identifiers that can be used to filter
+    and sort the model. For convenience, the \l identifiersFromItem() function can be used to
+    return all properties of a QMetaObject based type.
+    Afterwards the filter query can be set on the QIfFilterAndBrowseModel and will result in a
+    call to setupFilter(). All following calls to retrieve the content of the model need to work
+    on the filtered data.
+
+    \section1 Changing Model Data
+
+    To allow changing the Items within the model, the following capabilities can be set:
+    \list
+        \li \l{ModelCapabilities}{SupportsInsert}
+        \li \l{ModelCapabilities}{SupportsMove}
+        \li \l{ModelCapabilities}{SupportsRemove}
+    \endlist
+
+    Calls to one of the updating functions in \l QIfFilterAndBrowseModel are forwarded to the
+    matching function in the backend: \l insert, \l move and \l remove. All those functions need
+    to emit the \l {QIfPagingModelInterface::}{dataChanged} signal.
+
+    \sa QIfFilterAndBrowseModel
 */
 
 QIfFilterAndBrowseModelInterface::QIfFilterAndBrowseModelInterface(QObject *parent)
diff --git a/src/interfaceframework/qiffilterandbrowsemodelinterface.h b/src/interfaceframework/qiffilterandbrowsemodelinterface.h
index f10d61b8..637902a9 100644
--- a/src/interfaceframework/qiffilterandbrowsemodelinterface.h
+++ b/src/interfaceframework/qiffilterandbrowsemodelinterface.h
@@ -43,7 +43,6 @@ public:
 Q_SIGNALS:
     void canGoForwardChanged(const QUuid &identifier, const QVector<bool> &indexes, int start);
     void canGoBackChanged(const QUuid &identifier, bool canGoBack);
-    //does this really make sense ?
     void contentTypeChanged(const QUuid &identifier, const QString &contentType);
     void availableContentTypesChanged(const QStringList &availableContentTypes);
     void queryIdentifiersChanged(const QUuid &identifier, const QSet<QString> &queryIdentifiers);
diff --git a/src/interfaceframework/qifpagingmodelinterface.cpp b/src/interfaceframework/qifpagingmodelinterface.cpp
index 83355a4a..3db8ac60 100644
--- a/src/interfaceframework/qifpagingmodelinterface.cpp
+++ b/src/interfaceframework/qifpagingmodelinterface.cpp
@@ -20,13 +20,63 @@ QT_BEGIN_NAMESPACE
 
     The interface is discovered by a \l QIfPagingModel object, which connects to it and sets it up.
 
+    \section1 QIfPagingModel registration
+
     Every QIfPagingModel generates its own QUuid which is passed to the backend interface and can
-    be used to identify a model instance.
+    be used to identify a model instance. By using the QUuid of a specific instance in a signal,
+    only this specific instance gets notified about the change. This can be useful for stateful
+    backends, such as an addressbook with a filter function. Because of the filtering, the number
+    of items inside the model will change. The notification and the filtering itself is only done
+    for the specific instance which requested it. All other instances could still display the full
+    set of model data. The QIfFilterAndBrowseModel is using this concept for filtering. To inform
+    all feature instances of a change, a default constructed QUuid can be used instead.
+
+    The \l registerInstance and \l unregisterInstance functions are called respectively when a new
+    QIfPagingModel instance connects to this backend or disconnects from it.
+
+    \section1 Capabilities
+
+    Depending on the data of the model and the underlying store the data is coming from, different
+    features might be supported. The \l supportedCapabilitiesChanged signal informs the
+    QIfPagingModel instance about the features supported by this backend. The \l
+    {ModelCapabilities} type used in this signal hosts different features supported in the
+    QIfPagingModel and the QIfFilterAndBrowseModel.
+
+    For a QIfPagingModel, the \l {ModelCapabilities}{SupportsGetSize}
+    capability can be used to indicate that this backend knows the total size of the model and that
+    it will inform about it using the \l countChanged() signal. In case the capabilities are not
+    reported, or the SupportsGetSize capability is not set, the QIfPagingModel needs to use the
+    \l{QIfPagingModel::}{FetchMore} loading type.
+
+    \section1 Returning model data
+
+    Other than QIfFeatureInterface based backends, the \l initialize() function does not emit the
+    complete state. Instead the actual model data is returned on request. This is done to support
+    big models as well and save bandwidth when the data needs to be transferred over an IPC. Once a
+    QIfPagingModel is used inside a View class, the model data is requested from the backend by
+    calling \l fetchData(). The amount of data requested in one call can be controlled by the
+    QIfPagingModel instance. Once the requested data is ready, the backend needs to inform about it
+    using the
+    \l dataFetched() signal.
+    To inform the QIfPagingModel about an updated row, the dataChanged() signal can be used.
+
+    \section1 Example call order
+
+    \list 1
+        \li A QIfPagingModel instance is created and connects to this backend
+        \li \l initialize() is called
+        \li The backend initializes it's internal state and informs about all extra properties it
+            has by emitting the respective change signals.
+        \li The backend emits \l initializationDone()
+        \li The QIfPagingModel instance calls \l registerInstance() with its own QUuid
+        \li The backend informs about its capabilities and its size by emitting
+            \l supportedCapabilitiesChanged() and \l countChanged().
+        \li The QIfPagingModel fetches the first rows by calling \l fetchData()
+        \li The backend emits dataFetched() once it is ready.
+        \li The last two steps might repeat depending on the current state of the view
+    \endlist
 
     \sa QIfPagingModel
-
-    //TODO explain how the interface works on a example
-    <example of a fully featured backend>
 */
 
 /*!
diff --git a/src/interfaceframework/qtinterfaceframeworkmodule.cpp b/src/interfaceframework/qtinterfaceframeworkmodule.cpp
index 558c989f..b4e61fba 100644
--- a/src/interfaceframework/qtinterfaceframeworkmodule.cpp
+++ b/src/interfaceframework/qtinterfaceframeworkmodule.cpp
@@ -75,6 +75,7 @@ QtInterfaceFrameworkModule::QtInterfaceFrameworkModule(QObject *parent)
 
 /*!
     \enum QtInterfaceFrameworkModule::ModelCapability
+    \target ModelCapabilities
     \value NoExtras
            The backend does only support the minimum feature set and is stateful.
     \value SupportsGetSize