Improve data mapping documentation.

Task-number: QTRD-2133
Change-Id: I8f25fc7a3d15712060a1d100ec4d9895cc4b6637
Reviewed-by: Tomi Korpipää <tomi.korpipaa@digia.com>

9 files changed, 139 insertions, 51 deletions

diff --git a/src/datavis3d/data/qabstractdatamapping.cpp b/src/datavis3d/data/qabstractdatamapping.cpp
index ab5bdf5b..f85983ec 100644
--- a/src/datavis3d/data/qabstractdatamapping.cpp
+++ b/src/datavis3d/data/qabstractdatamapping.cpp
@@ -23,10 +23,12 @@ QT_DATAVIS3D_BEGIN_NAMESPACE
 /*!
  * \class QAbstractDataMapping
  * \inmodule QtDataVis3D
- * \brief Abstract base class for data mappings
+ * \brief Abstract base class for QtDataVis3D data mapping classes.
  * \since 1.0.0
  *
- * Data mapping classes provide a way to map data from one data source to another.
+ * Data mapping classes provide a way to map data from an external data source to one of
+ * QtDataVis3D data proxies.
+ * \sa QItemModelBarDataMapping, QItemModelScatterDataMapping
  */
 
 /*!
@@ -45,6 +47,12 @@ QAbstractDataMapping::~QAbstractDataMapping()
 {
 }
 
+/*!
+ * \fn void QAbstractDataMapping::mappingChanged()
+ *
+ * Emitted when any mapping has changed.
+ */
+
 // QItemModelBarDataMappingPrivate
 
 QAbstractDataMappingPrivate::QAbstractDataMappingPrivate(QAbstractDataMapping *q,
diff --git a/src/datavis3d/data/qabstractdatamapping.h b/src/datavis3d/data/qabstractdatamapping.h
index edc4b8ee..7f91c7ae 100644
--- a/src/datavis3d/data/qabstractdatamapping.h
+++ b/src/datavis3d/data/qabstractdatamapping.h
@@ -34,8 +34,6 @@ public:
     explicit QAbstractDataMapping(QAbstractDataMappingPrivate *d, QObject *parent = 0);
     virtual ~QAbstractDataMapping();
 
-    QAbstractDataProxy::DataType type() const;
-
 signals:
     void mappingChanged();
 
diff --git a/src/datavis3d/data/qitemmodelbardatamapping.cpp b/src/datavis3d/data/qitemmodelbardatamapping.cpp
index 6bc92f2c..d9b8403b 100644
--- a/src/datavis3d/data/qitemmodelbardatamapping.cpp
+++ b/src/datavis3d/data/qitemmodelbardatamapping.cpp
@@ -26,10 +26,22 @@ QT_DATAVIS3D_BEGIN_NAMESPACE
  * \brief Data model mapping for Q3DBars.
  * \since 1.0.0
  *
- * QItemModelBarDataMapping is used to define roles for mapping data in QAbstractItemModel to
- * Q3DBars.
+ * QItemModelBarDataMapping is used to map roles of QAbstractItemModel to rows, columns, and values
+ * of Q3DBars. There are two ways to use QItemModelBarDataMapping:
  *
- * TO BE CHECKED (add more explanations and/or example)
+ * 1) By default, the QItemModelBarDataMapping will map the rows and columns of QAbstractItemModel
+ *    to rows and columns of Q3DBars, and uses the value returned for Qt::DisplayRole as bar value.
+ *    The value role to be used can be redefined if Qt::DisplayRole is not suitable.
+ *
+ * 2) For models that do not have data already neatly sorted into rows and columns, such as
+ *    QAbstractListModel based models, you can define a list of categories for both rows and columns,
+ *    and define a role to map for each of row, column and value.
+ *    For example, assume that you have a custom QAbstractItemModel for storing various monthly values
+ *    related to a business.
+ *    Each item in the model has roles "year", "month", "income", and "expenses".
+ *    You could do the following to display the data in a bar chart:
+ *
+ *    \snippet doc_src_qtdatavis3d.cpp 3
  *
  * \sa QItemModelBarDataProxy
  */
@@ -160,8 +172,6 @@ QStringList QItemModelBarDataMapping::columnCategories() const
 /*!
  * Changes \a rowRole, \a columnRole, \a valueRole, \a rowCategories and \a columnCategories to the
  * mapping.
- *
- * Emits mappingChanged() signal after remapping.
  */
 void QItemModelBarDataMapping::remap(const QString &rowRole,
                                      const QString &columnRole,
@@ -178,11 +188,17 @@ void QItemModelBarDataMapping::remap(const QString &rowRole,
     emit mappingChanged();
 }
 
+/*!
+ * \internal
+ */
 QItemModelBarDataMappingPrivate *QItemModelBarDataMapping::dptr()
 {
     return static_cast<QItemModelBarDataMappingPrivate *>(d_ptr.data());
 }
 
+/*!
+ * \internal
+ */
 const QItemModelBarDataMappingPrivate *QItemModelBarDataMapping::dptrc() const
 {
     return static_cast<const QItemModelBarDataMappingPrivate *>(d_ptr.data());
diff --git a/src/datavis3d/data/qitemmodelbardataproxy.cpp b/src/datavis3d/data/qitemmodelbardataproxy.cpp
index 6cd3b027..8a25f123 100644
--- a/src/datavis3d/data/qitemmodelbardataproxy.cpp
+++ b/src/datavis3d/data/qitemmodelbardataproxy.cpp
@@ -29,7 +29,10 @@ QT_DATAVIS3D_BEGIN_NAMESPACE
  * \since 1.0.0
  *
  * QItemModelBarDataProxy allows you to use QAbstractItemModel derived models as a data source
- * for Q3DBars. It maps roles defined in QItemModelBarDataMapping to roles in the model.
+ * for Q3DBars. It uses QItemModelBarDataMapping instance to map data from the model to Q3DBars
+ * graph.
+ *
+ * \sa QItemModelBarDataMapping
  */
 
 /*!
@@ -77,10 +80,10 @@ const QAbstractItemModel *QItemModelBarDataProxy::itemModel() const
 }
 
 /*!
- * \property QItemModelBarDataProxy::mapping
+ * \property QItemModelBarDataProxy::activeMapping
  *
- * Defines data mapping. Does not take ownership of the mapping, but does connect to it to listen
- * for changes. Modifying a mapping that is set to the proxy will trigger data set re-resolving.
+ * Defines data mapping. Proxy takes ownership of the \a mapping.
+ * Modifying a mapping that is set to the proxy will trigger data set re-resolving.
  */
 void QItemModelBarDataProxy::setActiveMapping(QItemModelBarDataMapping *mapping)
 {
@@ -92,16 +95,27 @@ QItemModelBarDataMapping *QItemModelBarDataProxy::activeMapping() const
     return static_cast<QItemModelBarDataMapping *>(dptrc()->m_itemModelHandler->activeMapping());
 }
 
+/*!
+ * Transfers the ownership of the \a mapping to this proxy. The mapping is not taken to use yet.
+ * \sa setActiveMapping(), releaseMapping()
+ */
 void QItemModelBarDataProxy::addMapping(QItemModelBarDataMapping *mapping)
 {
     dptr()->m_itemModelHandler->addMapping(mapping);
 }
 
+/*!
+ * Releases the ownership of the \a mapping back to the caller. If the mapping was the currently
+ * active one, no mapping remains active after this call.
+ */
 void QItemModelBarDataProxy::releaseMapping(QItemModelBarDataMapping *mapping)
 {
     dptr()->m_itemModelHandler->releaseMapping(mapping);
 }
 
+/*!
+ * \return list of mappings owned by the proxy.
+ */
 QList<QItemModelBarDataMapping *> QItemModelBarDataProxy::mappings() const
 {
     QList<QItemModelBarDataMapping *> retList;
@@ -120,6 +134,9 @@ QItemModelBarDataProxyPrivate *QItemModelBarDataProxy::dptr()
     return static_cast<QItemModelBarDataProxyPrivate *>(d_ptr.data());
 }
 
+/*!
+ * \internal
+ */
 const QItemModelBarDataProxyPrivate *QItemModelBarDataProxy::dptrc() const
 {
     return static_cast<const QItemModelBarDataProxyPrivate *>(d_ptr.data());
diff --git a/src/datavis3d/data/qitemmodelmapdataproxy.cpp b/src/datavis3d/data/qitemmodelmapdataproxy.cpp
index 9d607645..6288d979 100644
--- a/src/datavis3d/data/qitemmodelmapdataproxy.cpp
+++ b/src/datavis3d/data/qitemmodelmapdataproxy.cpp
@@ -77,8 +77,8 @@ const QAbstractItemModel *QItemModelMapDataProxy::itemModel() const
 /*!
  * \property QItemModelMapDataProxy::activeMapping
  *
- * Defines data mapping. Does not take ownership of the mapping, but does connect to it to listen
- * for changes. Modifying a mapping that is set to the proxy will trigger data set re-resolving.
+ * Defines data mapping. Proxy takes ownership of the \a mapping.
+ * Modifying a mapping that is set to the proxy will trigger data set re-resolving.
  */
 void QItemModelMapDataProxy::setActiveMapping(QItemModelMapDataMapping *mapping)
 {
@@ -98,6 +98,9 @@ QItemModelMapDataProxyPrivate *QItemModelMapDataProxy::dptr()
     return static_cast<QItemModelMapDataProxyPrivate *>(d_ptr.data());
 }
 
+/*!
+ * \internal
+ */
 const QItemModelMapDataProxyPrivate *QItemModelMapDataProxy::dptrc() const
 {
     return static_cast<const QItemModelMapDataProxyPrivate *>(d_ptr.data());
diff --git a/src/datavis3d/data/qitemmodelscatterdatamapping.cpp b/src/datavis3d/data/qitemmodelscatterdatamapping.cpp
index dca02bbf..db8dff9e 100644
--- a/src/datavis3d/data/qitemmodelscatterdatamapping.cpp
+++ b/src/datavis3d/data/qitemmodelscatterdatamapping.cpp
@@ -26,10 +26,18 @@ QT_DATAVIS3D_BEGIN_NAMESPACE
  * \brief Data model mapping for Q3DScatter.
  * \since 1.0.0
  *
- * QItemModelScatterDataMapping is used to define roles for mapping data in QAbstractItemModel to
- * Q3DScatter.
+ * QItemModelScatterDataMapping is used to map roles of QAbstractItemModel to the XYZ-values
+ * of Q3DScatter points.
  *
- * TO BE CHECKED (add more explanations and/or example)
+ * QItemModelScatterDataMapping ignores rows and columns of the QAbstractItemModel and treats
+ * all items equally. It requires the model to provide at least three roles for the data items
+ * that can be mapped to X, Y, and Z-values for the scatter points.
+ *
+ * For example, assume that you have a custom QAbstractItemModel for storing various measurements
+ * done on material samples, providing data for roles such as "density", "hardness" and
+ * "conductivity". You could visualize these properties on a scatter chart:
+ *
+ * \snippet doc_src_qtdatavis3d.cpp 4
  *
  * \sa QItemModelScatterDataProxy
  */
@@ -43,21 +51,18 @@ QItemModelScatterDataMapping::QItemModelScatterDataMapping(QObject *parent)
 }
 
 /*!
- * Constructs QItemModelScatterDataMapping with \a xPosRole, \a yPosRole, \a zPosRole,
- * \a valueRole and the given \a parent.
+ * Constructs QItemModelScatterDataMapping with \a xPosRole, \a yPosRole, \a zPosRole
+ * and the given \a parent.
  */
 QItemModelScatterDataMapping::QItemModelScatterDataMapping(const QString &xPosRole,
                                                            const QString &yPosRole,
                                                            const QString &zPosRole,
-                                                           const QString &valueRole,
                                                            QObject *parent)
     : QAbstractDataMapping(new QItemModelScatterDataMappingPrivate(this), parent)
 {
-    Q_UNUSED(valueRole);
     dptr()->m_xPosRole = xPosRole;
     dptr()->m_yPosRole = yPosRole;
     dptr()->m_zPosRole = zPosRole;
-    //d_ptr->m_valueRole = valueRole;
 }
 
 /*!
@@ -70,7 +75,7 @@ QItemModelScatterDataMapping::~QItemModelScatterDataMapping()
 /*!
  * \property QItemModelScatterDataMapping::xPosRole
  *
- * Defines the x position role for the mapping.
+ * Defines the X position role for the mapping.
  */
 void QItemModelScatterDataMapping::setXPosRole(const QString &role)
 {
@@ -86,7 +91,7 @@ QString QItemModelScatterDataMapping::xPosRole() const
 /*!
  * \property QItemModelScatterDataMapping::yPosRole
  *
- * Defines the y position role for the mapping.
+ * Defines the Y position role for the mapping.
  */
 void QItemModelScatterDataMapping::setYPosRole(const QString &role)
 {
@@ -102,7 +107,7 @@ QString QItemModelScatterDataMapping::yPosRole() const
 /*!
  * \property QItemModelScatterDataMapping::zPosRole
  *
- * Defines the z position role for the mapping.
+ * Defines the Z position role for the mapping.
  */
 void QItemModelScatterDataMapping::setZPosRole(const QString &role)
 {
@@ -115,39 +120,32 @@ QString QItemModelScatterDataMapping::zPosRole() const
     return dptrc()->m_zPosRole;
 }
 
-//void QItemModelScatterDataMapping::setValueRole(const QString &role)
-//{
-//    d_ptr->m_valueRole = role;
-//    emit mappingChanged();
-//}
-
-//QString QItemModelScatterDataMapping::valueRole() const
-//{
-//    return d_ptr->m_valueRole;
-//}
-
 /*!
- * Changes \a xPosRole, \a yPosRole, \a zPosRole and \a valueRole to the mapping.
+ * Changes \a xPosRole, \a yPosRole and \a zPosRole to the mapping.
  *
  * Emits mappingChanged() signal after remapping.
  */
 void QItemModelScatterDataMapping::remap(const QString &xPosRole, const QString &yPosRole,
-                                         const QString &zPosRole, const QString &valueRole)
+                                         const QString &zPosRole)
 {
-    Q_UNUSED(valueRole);
     dptr()->m_xPosRole = xPosRole;
     dptr()->m_yPosRole = yPosRole;
     dptr()->m_zPosRole = zPosRole;
-    //d_ptr->m_valueRole = valueRole;
 
     emit mappingChanged();
 }
 
+/*!
+ * \internal
+ */
 QItemModelScatterDataMappingPrivate *QItemModelScatterDataMapping::dptr()
 {
     return static_cast<QItemModelScatterDataMappingPrivate *>(d_ptr.data());
 }
 
+/*!
+ * \internal
+ */
 const QItemModelScatterDataMappingPrivate *QItemModelScatterDataMapping::dptrc() const
 {
     return static_cast<const QItemModelScatterDataMappingPrivate *>(d_ptr.data());
diff --git a/src/datavis3d/data/qitemmodelscatterdatamapping.h b/src/datavis3d/data/qitemmodelscatterdatamapping.h
index 1a162b57..2f64f38c 100644
--- a/src/datavis3d/data/qitemmodelscatterdatamapping.h
+++ b/src/datavis3d/data/qitemmodelscatterdatamapping.h
@@ -33,13 +33,11 @@ class QT_DATAVIS3D_EXPORT QItemModelScatterDataMapping : public QAbstractDataMap
     Q_PROPERTY(QString xPosRole READ xPosRole WRITE setXPosRole)
     Q_PROPERTY(QString yPosRole READ yPosRole WRITE setYPosRole)
     Q_PROPERTY(QString zPosRole READ zPosRole WRITE setZPosRole)
-    //Q_PROPERTY(QString valueRole READ valueRole WRITE setValueRole)
 
 public:
     explicit QItemModelScatterDataMapping(QObject *parent = 0);
     QItemModelScatterDataMapping(const QString &xPosRole, const QString &yPosRole,
-                                 const QString &zPosRole, const QString &valueRole,
-                                 QObject *parent = 0);
+                                 const QString &zPosRole, QObject *parent = 0);
     virtual ~QItemModelScatterDataMapping();
 
     void setXPosRole(const QString &role);
@@ -48,12 +46,8 @@ public:
     QString yPosRole() const;
     void setZPosRole(const QString &role);
     QString zPosRole() const;
-    // TODO: This is a placeholder for scatter item size
-    //void setValueRole(const QString &role);
-    //QString valueRole() const;
 
-    void remap(const QString &xPosRole, const QString &yPosRole, const QString &zPosRole,
-               const QString &valueRole);
+    void remap(const QString &xPosRole, const QString &yPosRole, const QString &zPosRole);
 
 protected:
     QItemModelScatterDataMappingPrivate *dptr();
diff --git a/src/datavis3d/data/qitemmodelscatterdataproxy.cpp b/src/datavis3d/data/qitemmodelscatterdataproxy.cpp
index c802d91d..dfd10d8d 100644
--- a/src/datavis3d/data/qitemmodelscatterdataproxy.cpp
+++ b/src/datavis3d/data/qitemmodelscatterdataproxy.cpp
@@ -78,8 +78,8 @@ const QAbstractItemModel *QItemModelScatterDataProxy::itemModel() const
 /*!
  * \property QItemModelScatterDataProxy::activeMapping
  *
- * Defines data mapping. Does not take ownership of the mapping, but does connect to it to listen
- * for changes. Modifying a mapping that is set to the proxy will trigger data set re-resolving.
+ * Defines data mapping. Proxy takes ownership of the \a mapping.
+ * Modifying a mapping that is set to the proxy will trigger data set re-resolving.
  */
 void QItemModelScatterDataProxy::setActiveMapping(QItemModelScatterDataMapping *mapping)
 {
@@ -91,16 +91,27 @@ QItemModelScatterDataMapping *QItemModelScatterDataProxy::activeMapping() const
     return static_cast<QItemModelScatterDataMapping *>(dptrc()->m_itemModelHandler->activeMapping());
 }
 
+/*!
+ * Transfers the ownership of the \a mapping to this proxy. The mapping is not taken to use yet.
+ * \sa setActiveMapping(), releaseMapping()
+ */
 void QItemModelScatterDataProxy::addMapping(QItemModelScatterDataMapping *mapping)
 {
     dptr()->m_itemModelHandler->addMapping(mapping);
 }
 
+/*!
+ * Releases the ownership of the \a mapping back to the caller. If the mapping was the currently
+ * active one, no mapping remains active after this call.
+ */
 void QItemModelScatterDataProxy::releaseMapping(QItemModelScatterDataMapping *mapping)
 {
     dptr()->m_itemModelHandler->releaseMapping(mapping);
 }
 
+/*!
+ * \return list of mappings owned by the proxy.
+ */
 QList<QItemModelScatterDataMapping *> QItemModelScatterDataProxy::mappings() const
 {
     QList<QItemModelScatterDataMapping *> retList;
@@ -119,6 +130,9 @@ QItemModelScatterDataProxyPrivate *QItemModelScatterDataProxy::dptr()
     return static_cast<QItemModelScatterDataProxyPrivate *>(d_ptr.data());
 }
 
+/*!
+ * \internal
+ */
 const QItemModelScatterDataProxyPrivate *QItemModelScatterDataProxy::dptrc() const
 {
     return static_cast<const QItemModelScatterDataProxyPrivate *>(d_ptr.data());
diff --git a/src/datavis3d/doc/snippets/doc_src_qtdatavis3d.cpp b/src/datavis3d/doc/snippets/doc_src_qtdatavis3d.cpp
index b4a2b152..269ea520 100644
--- a/src/datavis3d/doc/snippets/doc_src_qtdatavis3d.cpp
+++ b/src/datavis3d/doc/snippets/doc_src_qtdatavis3d.cpp
@@ -27,3 +27,43 @@ proxy->setItemLabelFormat(QStringLiteral("@valueTitle for (@rowLabel, @colLabel)
 //! [2]
 proxy->setItemLabelFormat(QStringLiteral("@xTitle: @xValue, @yTitle: @yValue, @zTitle: @zValue"));
 //! [2]
+
+//! [3]
+// By defining row and column categories, you tell the mapping which row and column each item
+// belongs to. The categories must match the data stored in the model in the roles you define
+// for row and column mapping. In this example we expect "year" role to return four digit year
+// and "month" to return three letter designation for the month.
+//
+// An example of an item in model would be:
+// Requested role -> Returned data
+// "year" -> "2006" // Matches the first row category, so this item is added to the first row.
+// "month" -> "jan" // Matches the first column category, so this item is added as first item in the row.
+// "income" -> "12.1"
+// "expenses" -> "9.2"
+QStringList years;
+QStringList months;
+years << "2006" << "2007" << "2008" << "2009" << "2010" << "2011" << "2012";
+months << "jan" << "feb" << "mar" << "apr" << "may" << "jun" << "jul" << "aug" << "sep" << "oct" << "nov" << "dec";
+
+QItemModelBarDataMapping *mapping = new QItemModelBarDataMapping(QStringLiteral("year"), // Row role
+                                                                 QStringLiteral("month"), // Column role
+                                                                 QStringLiteral("income"), // Value role
+                                                                 years, // Row categories
+                                                                 months); // Column categories
+
+QItemModelBarDataProxy *proxy = new QItemModelBarDataProxy(customModel, mapping);
+
+//...
+
+// To display different data later, you can simply change the mapping of the current
+// mapping object, or set another mapping object.
+proxy->activeMapping()->setValueRole(QStringLiteral("expenses"));
+//! [3]
+
+//! [4]
+// Map "density" value to X-axis, "hardness" to Y-axis and "conductivity" to Z-axis.
+QItemModelScatterDataMapping *mapping = new QItemModelScatterDataMapping(QStringLiteral("density"),
+                                                                         QStringLiteral("hardness"),
+                                                                         QStringLiteral("conductivity"))
+QItemModelScatterDataProxy *proxy = new QItemModelScatterDataProxy(customModel, mapping);
+//! [4]