Fix documentation related to multiseries changes.

Also fixed some other miscellaneous issues.

Task-number: QTRD-2558
Change-Id: I2da3f7e64fbbbb287ddb7845cb0a15006dc4d6f5
Reviewed-by: Mika Salmela <mika.salmela@digia.com>

7 files changed, 95 insertions, 85 deletions

diff --git a/src/datavisualization/data/qabstract3dseries.cpp b/src/datavisualization/data/qabstract3dseries.cpp
index 0ebf2aa1..579e1dec 100644
--- a/src/datavisualization/data/qabstract3dseries.cpp
+++ b/src/datavisualization/data/qabstract3dseries.cpp
@@ -26,7 +26,7 @@ QT_DATAVISUALIZATION_BEGIN_NAMESPACE
 /*!
  * \class QAbstract3DSeries
  * \inmodule QtDataVisualization
- * \brief Base class for all QtDataVisualization data proxies.
+ * \brief Base class for all QtDataVisualization series.
  * \since Qt Data Visualization 1.0
  *
  * You use the visualization type specific inherited classes instead of the base class.
@@ -39,7 +39,7 @@ QT_DATAVISUALIZATION_BEGIN_NAMESPACE
  * \since QtDataVisualization 1.0
  * \ingroup datavisualization_qml
  * \instantiates QAbstract3DSeries
- * \brief Base type for all QtDataVisualization data proxies.
+ * \brief Base type for all QtDataVisualization series.
  *
  * This type is uncreatable, but contains properties that are exposed via subtypes.
  * \sa Bar3DSeries, Scatter3DSeries, Surface3DSeries, {Qt Data Visualization Data Handling}
@@ -111,7 +111,7 @@ QAbstract3DSeries::SeriesType QAbstract3DSeries::type() const
  * for example, when an item is selected. How the format is interpreted depends on series type. See
  * each series class documentation for more information.
  *
- * \sa QBar3DSeries, Q3DScatterSeries, Q3DSurfaceSeries
+ * \sa QBar3DSeries, QScatter3DSeries, QSurface3DSeries
  */
 void QAbstract3DSeries::setItemLabelFormat(const QString &format)
 {
diff --git a/src/datavisualization/data/qbar3dseries.cpp b/src/datavisualization/data/qbar3dseries.cpp
index 0e6bdd60..301f36f1 100644
--- a/src/datavisualization/data/qbar3dseries.cpp
+++ b/src/datavisualization/data/qbar3dseries.cpp
@@ -30,15 +30,8 @@ QT_DATAVISUALIZATION_BEGIN_NAMESPACE
  * QBar3DSeries manages the series specific visual elements, as well as series data
  * (via data proxy).
  *
- * If no data proxy is set explicitly for the series, QBar3DSeries creates a default
- * proxy. If any other proxy is set as active data proxy later, the default proxy and all data
- * added to it are destroyed.
- *
- * QBar3DSeries optionally keeps track of row and column labels, which Q3DCategoryAxis can utilize
- * to show axis labels. The row and column labels are stored in separate array from the data and
- * row manipulation methods provide an alternate versions that don't affect the row labels.
- * This enables the option of having row labels that relate to the position of the data in the
- * array rather than the data itself.
+ * If no data proxy is set explicitly for the series, the series creates a default
+ * proxy. Setting another proxy will destroy the existing proxy and all data added to it.
  *
  * QBar3DSeries supports the following format tags for QAbstract3DSeries::setItemLabelFormat():
  * \table
@@ -86,6 +79,31 @@ QT_DATAVISUALIZATION_BEGIN_NAMESPACE
  * \sa {Qt Data Visualization Data Handling}
  */
 
+/*!
+ * \qmlproperty BarDataProxy Bar3DSeries::dataProxy
+ *
+ * This property holds the active data \a proxy. The series assumes ownership of any proxy set to
+ * it and deletes any previously set proxy when a new one is added. The \a proxy cannot be null or
+ * set to another series.
+ */
+
+/*!
+ * \qmlproperty point Bar3DSeries::selectedBar
+ *
+ * Selects a bar at the \a position. The \a position is the (row, column) position in
+ * the data array of the series.
+ * Only one bar can be selected at a time.
+ * To clear selection, set invalidSelectionPosition() as the \a position.
+ * If this series is added to a graph, the graph can adjust the selection according to user
+ * interaction or if it becomes invalid. Selecting a bar on another added series will also
+ * clear the selection.
+ */
+
+/*!
+ * \qmlmethod point Bar3DSeries::invalidSelectionPosition()
+ * \return an invalid position for selection. Set this position to selectedBar property if you
+ * want to clear the selection.
+ */
 
 /*!
  * Constructs QBar3DSeries with the given \a parent.
@@ -97,6 +115,9 @@ QBar3DSeries::QBar3DSeries(QObject *parent) :
     dptr()->setDataProxy(new QBarDataProxy);
 }
 
+/*!
+ * Constructs QBar3DSeries with the given \a dataProxy and the \a parent.
+ */
 QBar3DSeries::QBar3DSeries(QBarDataProxy *dataProxy, QObject *parent) :
     QAbstract3DSeries(new QBar3DSeriesPrivate(this), parent)
 {
diff --git a/src/datavisualization/data/qbardataproxy.cpp b/src/datavisualization/data/qbardataproxy.cpp
index 26c3a36a..d22c34b5 100644
--- a/src/datavisualization/data/qbardataproxy.cpp
+++ b/src/datavisualization/data/qbardataproxy.cpp
@@ -44,32 +44,6 @@ QT_DATAVISUALIZATION_BEGIN_NAMESPACE
  * This enables the option of having row labels that relate to the position of the data in the
  * array rather than the data itself.
  *
- * QBarDataProxy supports the following format tags for QAbstractDataProxy::setItemLabelFormat():
- * \table
- *   \row
- *     \li @rowTitle      \li Title from row axis
- *   \row
- *     \li @colTitle      \li Title from column axis
- *   \row
- *     \li @valueTitle    \li Title from value axis
- *   \row
- *     \li @rowIdx        \li Visible row index
- *   \row
- *     \li @colIdx        \li Visible Column index
- *   \row
- *     \li @rowLabel      \li Label from row axis
- *   \row
- *     \li @colLabel      \li Label from column axis
- *   \row
- *     \li @valueLabel    \li Item value formatted using the same format the value axis attached to the graph uses,
- *                            see \l{Q3DValueAxis::setLabelFormat()} for more information.
- *   \row
- *     \li %<format spec> \li Item value in specified format.
- * \endtable
- *
- * For example:
- * \snippet doc_src_qtdatavisualization.cpp 1
- *
  * \sa {Qt Data Visualization Data Handling}
  */
 
diff --git a/src/datavisualization/data/qscatter3dseries.cpp b/src/datavisualization/data/qscatter3dseries.cpp
index aff0f33c..4d9eb01a 100644
--- a/src/datavisualization/data/qscatter3dseries.cpp
+++ b/src/datavisualization/data/qscatter3dseries.cpp
@@ -30,9 +30,8 @@ QT_DATAVISUALIZATION_BEGIN_NAMESPACE
  * QScatter3DSeries manages the series specific visual elements, as well as series data
  * (via data proxy).
  *
- * If no data proxy is set explicitly for the series, QScatter3DSeries creates a default
- * proxy. If any other proxy is set as active data proxy later, the default proxy and all data
- * added to it are destroyed.
+ * If no data proxy is set explicitly for the series, the series creates a default
+ * proxy. Setting another proxy will destroy the existing proxy and all data added to it.
  *
  * QScatter3DSeries supports the following format tags for QAbstract3DSeries::setItemLabelFormat():
  * \table
@@ -76,6 +75,30 @@ QT_DATAVISUALIZATION_BEGIN_NAMESPACE
  * \sa {Qt Data Visualization Data Handling}
  */
 
+/*!
+ * \qmlproperty ScatterDataProxy Scatter3DSeries::dataProxy
+ *
+ * This property holds the active data \a proxy. The series assumes ownership of any proxy set to
+ * it and deletes any previously set proxy when a new one is added. The \a proxy cannot be null or
+ * set to another series.
+ */
+
+/*!
+ * \qmlproperty int Scatter3DSeries::selectedItem
+ *
+ * Selects an item at the \a index. The \a index is the index in the data array of the series.
+ * Only one item can be selected at a time.
+ * To clear selection, set invalidSelectionIndex() as the \a index.
+ * If this series is added to a graph, the graph can adjust the selection according to user
+ * interaction or if it becomes invalid. Selecting an item on another added series will also
+ * clear the selection.
+ */
+
+/*!
+ * \qmlmethod int Scatter3DSeries::invalidSelectionIndex()
+ * \return an invalid index for selection. Set this index to selectedItem property if you
+ * want to clear the selection.
+ */
 
 /*!
  * Constructs QScatter3DSeries with the given \a parent.
@@ -87,6 +110,9 @@ QScatter3DSeries::QScatter3DSeries(QObject *parent) :
     dptr()->setDataProxy(new QScatterDataProxy);
 }
 
+/*!
+ * Constructs QScatter3DSeries with the given \a dataProxy and the \a parent.
+ */
 QScatter3DSeries::QScatter3DSeries(QScatterDataProxy *dataProxy, QObject *parent) :
     QAbstract3DSeries(new QScatter3DSeriesPrivate(this), parent)
 {
diff --git a/src/datavisualization/data/qscatterdataproxy.cpp b/src/datavisualization/data/qscatterdataproxy.cpp
index 149cb1ae..ff37dd24 100644
--- a/src/datavisualization/data/qscatterdataproxy.cpp
+++ b/src/datavisualization/data/qscatterdataproxy.cpp
@@ -32,28 +32,6 @@ QT_DATAVISUALIZATION_BEGIN_NAMESPACE
  *
  * QScatterDataProxy takes ownership of all QScatterDataArrays and QScatterDataItems passed to it.
  *
- * QScatterDataProxy supports the following format tags for QAbstractDataProxy::setItemLabelFormat():
- * \table
- *   \row
- *     \li @xTitle    \li Title from X axis
- *   \row
- *     \li @yTitle    \li Title from Y axis
- *   \row
- *     \li @zTitle    \li Title from Z axis
- *   \row
- *     \li @xLabel    \li Item value formatted using the same format the X axis attached to the graph uses,
- *                            see \l{Q3DValueAxis::setLabelFormat()} for more information.
- *   \row
- *     \li @yLabel    \li Item value formatted using the same format the Y axis attached to the graph uses,
- *                            see \l{Q3DValueAxis::setLabelFormat()} for more information.
- *   \row
- *     \li @zLabel    \li Item value formatted using the same format the Z axis attached to the graph uses,
- *                            see \l{Q3DValueAxis::setLabelFormat()} for more information.
- * \endtable
- *
- * For example:
- * \snippet doc_src_qtdatavisualization.cpp 2
- *
  * \sa {Qt Data Visualization Data Handling}
  */
 
diff --git a/src/datavisualization/data/qsurface3dseries.cpp b/src/datavisualization/data/qsurface3dseries.cpp
index 98d406c0..d71962c3 100644
--- a/src/datavisualization/data/qsurface3dseries.cpp
+++ b/src/datavisualization/data/qsurface3dseries.cpp
@@ -30,9 +30,8 @@ QT_DATAVISUALIZATION_BEGIN_NAMESPACE
  * QSurface3DSeries manages the series specific visual elements, as well as series data
  * (via data proxy).
  *
- * If no data proxy is set explicitly for the series, QSurface3DSeries creates a default
- * proxy. If any other proxy is set as active data proxy later, the default proxy and all data
- * added to it are destroyed.
+ * If no data proxy is set explicitly for the series, the series creates a default
+ * proxy. Setting another proxy will destroy the existing proxy and all data added to it.
  *
  * QSurface3DSeries supports the following format tags for QAbstract3DSeries::setItemLabelFormat():
  * \table
@@ -76,6 +75,30 @@ QT_DATAVISUALIZATION_BEGIN_NAMESPACE
  * \sa {Qt Data Visualization Data Handling}
  */
 
+/*!
+ * \qmlproperty SurfaceDataProxy Surface3DSeries::dataProxy
+ *
+ * This property holds the active data \a proxy. The series assumes ownership of any proxy set to
+ * it and deletes any previously set proxy when a new one is added. The \a proxy cannot be null or
+ * set to another series.
+ */
+
+/*!
+ * \qmlproperty point Surface3DSeries::selectedPoint
+ *
+ * Selects a surface grid point in a \a position. The position is the (row, column) position in
+ * the data array of the series.
+ * Only one point can be selected at a time.
+ * To clear selection, set invalidSelectionPosition() as the \a position.
+ * If this series is added to a graph, the graph can adjust the selection according to user
+ * interaction or if it becomes invalid.
+ */
+
+/*!
+ * \qmlmethod point Surface3DSeries::invalidSelectionPosition()
+ * \return a point signifying an invalid selection position. Set this to selectedPoint property
+ * to clear the selection.
+ */
 
 /*!
  * Constructs QSurface3DSeries with the given \a parent.
@@ -87,6 +110,9 @@ QSurface3DSeries::QSurface3DSeries(QObject *parent) :
     dptr()->setDataProxy(new QSurfaceDataProxy);
 }
 
+/*!
+ * Constructs QSurface3DSeries with the given \a dataProxy and the \a parent.
+ */
 QSurface3DSeries::QSurface3DSeries(QSurfaceDataProxy *dataProxy, QObject *parent) :
     QAbstract3DSeries(new QSurface3DSeriesPrivate(this), parent)
 {
@@ -149,6 +175,10 @@ QPoint QSurface3DSeries::selectedPoint() const
     return dptrc()->m_selectedPoint;
 }
 
+/*!
+ * \return a QPoint signifying an invalid selection position. Set this to selectedPoint property
+ * to clear the selection.
+ */
 QPoint QSurface3DSeries::invalidSelectionPosition() const
 {
     return Surface3DController::invalidSelectionPosition();
diff --git a/src/datavisualization/data/qsurfacedataproxy.cpp b/src/datavisualization/data/qsurfacedataproxy.cpp
index e3c2714c..8db082c7 100644
--- a/src/datavisualization/data/qsurfacedataproxy.cpp
+++ b/src/datavisualization/data/qsurfacedataproxy.cpp
@@ -43,25 +43,6 @@ QT_DATAVISUALIZATION_BEGIN_NAMESPACE
  * \note Surfaces with less than two rows or columns are not considered valid surfaces and will
  * not get rendered.
  *
- * QSurfaceDataProxy supports the following format tags for QAbstractDataProxy::setItemLabelFormat():
- * \table
- *   \row
- *     \li @xTitle    \li Title from X axis
- *   \row
- *     \li @yTitle    \li Title from Y axis
- *   \row
- *     \li @zTitle    \li Title from Z axis
- *   \row
- *     \li @xLabel    \li Item value formatted using the same format as the X axis attached to the graph uses,
- *                            see \l{Q3DValueAxis::setLabelFormat()} for more information.
- *   \row
- *     \li @yLabel    \li Item value formatted using the same format as the Y axis attached to the graph uses,
- *                            see \l{Q3DValueAxis::setLabelFormat()} for more information.
- *   \row
- *     \li @zLabel    \li Item value formatted using the same format as the Z axis attached to the graph uses,
- *                            see \l{Q3DValueAxis::setLabelFormat()} for more information.
- * \endtable
- *
  * \sa {Qt Data Visualization Data Handling}
  */