[Docs] More API documentation review

Change-Id: Ida346f384bc45a2b92aff0e3912a519d3596142b
Reviewed-by: Dominik Holland <dominik.holland@pelagicore.com>

3 files changed, 53 insertions, 33 deletions

diff --git a/src/ivicore/doc/src/external-resources.qdoc b/src/ivicore/doc/src/external-resources.qdoc
index c48930b..6541ff5 100644
--- a/src/ivicore/doc/src/external-resources.qdoc
+++ b/src/ivicore/doc/src/external-resources.qdoc
@@ -29,3 +29,8 @@
     \externalpage https://doc.qt.io/QtAutomotiveSuite/index.html
     \title Qt Automotive Suite
 */
+
+/*!
+    \externalpage https://doc.qt.io/qt-5/qabstractlistmodel.html#subclassing
+    \title QAbstractListModel - Subclassing
+*/
diff --git a/src/ivicore/qiviabstractfeaturelistmodel.cpp b/src/ivicore/qiviabstractfeaturelistmodel.cpp
index 9316286..77a7fb0 100644
--- a/src/ivicore/qiviabstractfeaturelistmodel.cpp
+++ b/src/ivicore/qiviabstractfeaturelistmodel.cpp
@@ -125,14 +125,26 @@ QIviFeatureInterface *QIviAbstractFeatureListModelPrivate::backend() const
     \inmodule QtIviCore
     \brief The QIviAbstractFeatureListModel is the base class for QtIvi Features which should act as a model.
 
-    See QIviAbstractFeature for more details on how a Feature works. This base class is needed to avoid a diamond
-    inheritance from QAbstractListModel and QIviAbstractFeature.
+    This base class is necessary to avoid virtual inheritance from QAbstractListModel and
+    QIviAbstractFeature.
 
-    See the \l{Models} section for more information about all models in QtIvi.
+    For more details on how a Feature works, see QIviAbstractFeature.
+    For more information about models in QtIvi, see \l{Models}.
 
     \section1 Subclassing
 
-    //TODO add docs here.
+    Your QIviAbstractFeatureListModel subclass must provide implementations for all virtual
+    functions from QIviAbstractFeature as well as the virtual functions from QAbstractListModel.
+
+    \list
+        \li For more details on how to integrate with the \l{Dynamic Backend System}, see
+            \l{QIviAbstractFeature::Write a Subclass}{QIviAbstractFeature}.
+        \li For more details on what you need to do to provide the model's required
+            functionality, see \l{QAbstractListModel - Subclassing}.
+        \li For a class that implements all the necessary QIviAbstractFeatureListModel functions
+            to provide pagination functionality, see QIviPagingModel.
+    \endlist
+
 */
 
 /*!
@@ -142,13 +154,14 @@ QIviFeatureInterface *QIviAbstractFeatureListModelPrivate::backend() const
 
     \brief The QIviAbstractFeatureListModel is the base class for QtIvi Features which should act as a model.
 
-    See QIviAbstractFeature for more details on how a Feature works. This base class is needed to avoid a diamond
-    inheritance from QAbstractListModel and QIviAbstractFeature.
+    This base class is necessary to avoid virtual inheritance from QAbstractListModel and
+    QIviAbstractFeature.
 
-    This element is not directly accessible from QML. It provides the
-    base QML properties for the feature, like autoDiscovery and isValid.
+    This element is not directly accessible from QML. It provides the base QML properties for the
+    feature, like autoDiscovery and isValid.
 
-    See the \l{Models} section for more information about all models in QtIvi.
+    For more details on how a Feature works, see QIviAbstractFeature.
+    For more information about models in QtIvi, see \l{Models}.
 
     \sa AbstractFeature
 */
diff --git a/src/ivicore/qiviabstractzonedfeature.cpp b/src/ivicore/qiviabstractzonedfeature.cpp
index c3c2464..36836a5 100644
--- a/src/ivicore/qiviabstractzonedfeature.cpp
+++ b/src/ivicore/qiviabstractzonedfeature.cpp
@@ -136,10 +136,10 @@ void QIviAbstractZonedFeature::clearServiceObject()
 }
 
 /*!
-    Returns pointer to the backend \a interface
+    Returns a pointer to the backend \a interface.
 
-    Returns parent backend if parent is QIviAbstractZonedFeature type.
-    Returns zero if no backend connected.
+    Returns the parent backend, if the parent is a QIviAbstractZonedFeature type.
+    Returns zero if no backend is connected.
 */
 QIviZonedFeatureInterface *QIviAbstractZonedFeature::backend(const QString &interface) const
 {
@@ -158,22 +158,22 @@ QIviZonedFeatureInterface *QIviAbstractZonedFeature::backend(const QString &inte
 /*!
     \fn virtual QIviAbstractZonedFeature *QIviAbstractZonedFeature::createZoneFeature(const QString &zone) = 0
 
-    Create new child feature to the given \a zone.
+    Create a new child feature for the given \a zone.
 
-    Returns zero if feature can't be created for the given feature and zone.
+    Returns zero if the feature can't be created using the parameters specified.
 */
 
 /*!
     \qmlproperty QString AbstractZonedFeature::zone
 
-    \brief Name of the zone of this zoned feature.
+    \brief Name of the zone for this zoned feature.
 
-    The zone can be given in the feature initialization. With this property it's
-    possible to control only a single specific feature zone.
+    The zone can be given in the feature initialization. This property lets you control a single
+    specific feature zone only.
 
-    This property is writable only before the backend is connected. When the backend is
-    discovered and the component is verified to be valid, zone is not writable anymore.
-    It's not recommended to change the zone after the initialization.
+    This property is only writable before the backend is connected. Once the backend is
+    discovered and the component is verified to be valid, the zone is not writable anymore.
+    It's not recommended to change the zone after initialization.
 
     \qml
     ClimateControl {
@@ -189,12 +189,11 @@ QIviZonedFeatureInterface *QIviAbstractZonedFeature::backend(const QString &inte
 
     \brief Name of the zone of this zoned feature.
 
-    The zone can be given in the feature initialization. With this property it's
-    possible to control only a single specific feature zone.
+    The zone can be given in the feature initialization. With this property it's possible to
+    control only a single specific feature zone.
 
-    This property is writable only before the backend is connected. When the backend is
-    discovered and the component is verified to be valid, zone is not writable anymore.
-    It's not recommended to change the zone after the initialization.
+    This property is writable only before the backend is connected. Once the backend is discovered
+    and the component is verified to be valid, zone is not writable anymore.
 
     It's recommended to initialize the zone in the feature constructor:
 
@@ -203,6 +202,9 @@ QIviZonedFeatureInterface *QIviAbstractZonedFeature::backend(const QString &inte
     climateControl->startAutoDiscovery();
     QString zone = climateControl->zone();
     \endcode
+
+    After initialization, it's not recommended to change the zone.
+
 */
 QString QIviAbstractZonedFeature::zone() const
 {
@@ -247,12 +249,12 @@ void QIviAbstractZonedFeature::initializeZones(const QStringList &zones)
 /*!
     \qmlproperty QStringList AbstractZonedFeature::availableZones
 
-    List of the available zones.
+    Holds a list of the available zones.
 */
 /*!
     \property QIviAbstractZonedFeature::availableZones
 
-    List of the available zones.
+    Holds a list of the available zones.
 */
 QStringList QIviAbstractZonedFeature::availableZones() const
 {
@@ -262,7 +264,7 @@ QStringList QIviAbstractZonedFeature::availableZones() const
 
 
 /*!
-    Returns the given \a zone instance of the feature.
+    Returns the given \a zone instance for the feature.
 */
 QIviAbstractZonedFeature *QIviAbstractZonedFeature::zoneAt(const QString &zone) const
 {
@@ -274,7 +276,7 @@ QIviAbstractZonedFeature *QIviAbstractZonedFeature::zoneAt(const QString &zone)
 }
 
 /*!
-    Returns all zone instances of the feature.
+    Returns all zone instances for the feature.
 */
 QList<QIviAbstractZonedFeature*> QIviAbstractZonedFeature::zones() const
 {
@@ -290,7 +292,7 @@ QIviAbstractZonedFeature::QIviAbstractZonedFeature(QIviAbstractZonedFeaturePriva
 /*!
     \qmlproperty QVariantMap AbstractZonedFeature::zoneAt
 
-    Direct feature access to the given zone.
+    Provides direct feature access to the given zone.
 
     \code
     feature.zoneAt.FrontLeft
@@ -299,7 +301,7 @@ QIviAbstractZonedFeature::QIviAbstractZonedFeature(QIviAbstractZonedFeaturePriva
 /*!
     \property QIviAbstractZonedFeature::zoneAt
 
-    Direct feature access to the given zone.
+    Provides direct feature access to the given zone.
 */
 QVariantMap QIviAbstractZonedFeature::zoneFeatureMap() const
 {
@@ -310,7 +312,7 @@ QVariantMap QIviAbstractZonedFeature::zoneFeatureMap() const
 /*!
     \qmlproperty QVariantList AbstractZonedFeature::zones
 
-    Access to the feature zones model.
+    Provides access to the feature zones model.
 
     \code
     model: feature.zones
@@ -319,7 +321,7 @@ QVariantMap QIviAbstractZonedFeature::zoneFeatureMap() const
 /*!
     \property QIviAbstractZonedFeature::zones
 
-    Access to the feature zones model.
+    Provides access to the feature zones model.
 */
 QVariantList QIviAbstractZonedFeature::zoneFeatureList() const
 {