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>

4 files changed, 43 insertions, 56 deletions

diff --git a/src/datavisualization/doc/src/qtdatavisualization-qml-bars3d.qdoc b/src/datavisualization/doc/src/qtdatavisualization-qml-bars3d.qdoc
index 45324b8a..bb99a539 100644
--- a/src/datavisualization/doc/src/qtdatavisualization-qml-bars3d.qdoc
+++ b/src/datavisualization/doc/src/qtdatavisualization-qml-bars3d.qdoc
@@ -36,7 +36,7 @@
  *
  * See \l{Qt Quick 2 Bars Example} for more thorough usage example.
  *
- * \sa Bar3DSeries, ItemModelBarData, Scatter3D, Surface3D, {Qt Data Visualization C++ Classes}
+ * \sa Bar3DSeries, ItemModelBarDataProxy, Scatter3D, Surface3D, {Qt Data Visualization C++ Classes}
  */
 
 /*!
@@ -122,24 +122,23 @@
  */
 
 /*!
- * \qmlproperty point Bars3D::selectedBar
- * Position of the selected bar in data window. Only one bar can be selected at a time.
- * To clear selection, specify an illegal position, e.g. Qt.point(-1.0, -1.0).
- */
-
-/*!
- * \qmlproperty list<QBar3DSeries> seriesList
+ * \qmlproperty list<QBar3DSeries> Bars3D::seriesList
  * This property holds the series of the graph.
  * By default, this property contains an empty list.
  * To set the series, either use the addSeries() function or define them as children of the graph.
  */
 
 /*!
- * \qmlmethod void addSeries(QBar3DSeries *series)
- * Add the \a series to the graph.
+ * \qmlmethod void Bars3D::addSeries(QBar3DSeries *series)
+ * Adds the \a series to the graph. A graph can contain multiple series, but only one set of axes,
+ * so the rows and columns of all series must match for the visualized data to be meaningful.
+ * If the graph has multiple visible series, only the first one added will
+ * generate the row or column labels on the axes in cases where the labels are not explicitly set
+ * to the axes. If the newly added series has specified a selected bar, it will be highlighted and
+ * any existing selection will be cleared. Only one added series can have an active selection.
  */
 
 /*!
- * \qmlmethod void removeSeries(QBar3DSeries *series)
+ * \qmlmethod void Bars3D::removeSeries(QBar3DSeries *series)
  * Remove the \a series from the graph.
  */
diff --git a/src/datavisualization/doc/src/qtdatavisualization-qml-scatter3d.qdoc b/src/datavisualization/doc/src/qtdatavisualization-qml-scatter3d.qdoc
index 7ad9d470..da7faaa3 100644
--- a/src/datavisualization/doc/src/qtdatavisualization-qml-scatter3d.qdoc
+++ b/src/datavisualization/doc/src/qtdatavisualization-qml-scatter3d.qdoc
@@ -97,24 +97,20 @@
  */
 
 /*!
-  \qmlproperty int Scatter3D::selectedItemIndex
-  Selects an item in the \a index. Only one item can be selected at a time.
-  To clear selection, specify an illegal \a index, e.g. -1.
- */
-
-/*!
- * \qmlproperty list<QScatter3DSeries> seriesList
+ * \qmlproperty list<QScatter3DSeries> Scatter3D::seriesList
  * This property holds the series of the graph.
  * By default, this property contains an empty list.
  * To set the series, either use the addSeries() function or define them as children of the graph.
  */
 
 /*!
- * \qmlmethod void addSeries(QScatter3DSeries *series)
- * Add the \a series to the graph.
+ * \qmlmethod void Scatter3D::addSeries(QScatter3DSeries *series)
+ * Adds the \a series to the graph. A graph can contain multiple series, but has only one set of
+ * axes. If the newly added series has specified a selected item, it will be highlighted and
+ * any existing selection will be cleared. Only one added series can have an active selection.
  */
 
 /*!
- * \qmlmethod void removeSeries(QScatter3DSeries *series)
+ * \qmlmethod void Scatter3D::removeSeries(QScatter3DSeries *series)
  * Remove the \a series from the graph.
  */
diff --git a/src/datavisualization/doc/src/qtdatavisualization-qml-surface3d.qdoc b/src/datavisualization/doc/src/qtdatavisualization-qml-surface3d.qdoc
index d1422b10..f422a5b5 100644
--- a/src/datavisualization/doc/src/qtdatavisualization-qml-surface3d.qdoc
+++ b/src/datavisualization/doc/src/qtdatavisualization-qml-surface3d.qdoc
@@ -88,16 +88,7 @@
  */
 
 /*!
-  \qmlproperty point Surface3D::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, specify an illegal \a position, e.g. (-1, -1).
- */
-
-/*!
- * \qmlproperty list<QSurface3DSeries> seriesList
+ * \qmlproperty list<QSurface3DSeries> Surface3D::seriesList
  * This property holds the series of the graph.
  * By default, this property contains an empty list.
  * To set the series, either use the addSeries() function or define them as children of the graph.
@@ -105,11 +96,12 @@
  */
 
 /*!
- * \qmlmethod void addSeries(QSurface3DSeries *series)
- * Add the \a series to the graph.
+ * \qmlmethod void Surface3D::addSeries(QSurface3DSeries *series)
+ * Adds the \a series to the graph.
+ * \note The surface graph currently supports only a single series at a time.
  */
 
 /*!
- * \qmlmethod void removeSeries(QSurface3DSeries *series)
+ * \qmlmethod void Surface3D::removeSeries(QSurface3DSeries *series)
  * Remove the \a series from the graph.
  */
diff --git a/src/datavisualization/doc/src/qtdatavisualization.qdoc b/src/datavisualization/doc/src/qtdatavisualization.qdoc
index 3c697ba0..7716fb4c 100644
--- a/src/datavisualization/doc/src/qtdatavisualization.qdoc
+++ b/src/datavisualization/doc/src/qtdatavisualization.qdoc
@@ -173,7 +173,7 @@
     directly supported. Therefore, Qt Data Visualization implements data proxies into which
     user can feed their data in a known format. Each visualization type has a basic proxy type,
     which takes data in a format suitable for that visualization.
-    For example, the basic proxy for Q3DBars is QBarDataProxy, which stores rows of QBarDataItem
+    For example, the basic proxy for QBar3DSeries is QBarDataProxy, which stores rows of QBarDataItem
     objects. Each QBarDataItem stores a single bar value. Additional typedefs are provided for
     QBarDataArray and QBarDataRow containers.
 
@@ -182,32 +182,32 @@
 
     \snippet doc_src_qtdatavisualization.cpp 10
 
-    \note The graph objects can own more than one data proxy, but only one proxy can be
-    active at a time. If you need to switch back and forth between two different sets of data,
-    it may be more efficient to store each set in a different proxy and just change the active
-    proxy, rather than reset the data in one proxy every time you need to switch.
+    \note Series objects can own only a single proxy at a time. The existing proxy is deleted
+    when another is set to the series. Graphs can contain multiple series, though.
+    If you need to switch back and forth between two different sets of data,
+    it is usually more efficient to store each set in a different series and just change the series,
+    rather than reset the data in one proxy every time you need to switch.
 
     \section1 Item models and data mapping
 
     For common use cases, Qt Data Visualization offers specialized proxies. One such case is having
     data in an item model (QAbstractItemModel subclass), which is a common way to store data in
-    Qt applications. Each of the visualization types offers a special proxy and a corresponding mapping
-    class for this purpose, for example, QItemModelBarDataProxy and QItemModelBarDataMapping for Q3DBars.
+    Qt applications. Each of the visualization types offers a special proxy class for this purpose,
+    for example, QItemModelBarDataProxy for QBar3DSeries.
     These proxies are simple to use: just give them a pointer to the item model containing the
-    data and the mapping object containing rules how to map the data into format the basic proxy can
-    digest.
+    data and the rules how to map the data into format the basic proxy can digest.
 
-    Mapping objects work with item model roles. Each data item in the model can have different
-    values for different roles. For example, with QItemModelBarDataMapping you can specify which
+    Mapping works with item model roles. Each data item in the model can have different
+    values for different roles. For example, with QItemModelBarDataProxy you can specify which
     role is used to determine which row the item belongs to, which role does the same for columns,
     and which role specifies the value of the item. When the proxy resolves the data from the model,
     it uses these mappings to generate the rows and columns of the bar graph.
 
-    Depending on the visualization type, mapping classes may support other functionalities as well,
-    such as QItemModelBarDataMapping optionally mapping QAbstractItemModel rows and columns directly
-    into bar graph rows and columns. See individual mapping classes for more information and examples
-    about how to use them: QItemModelBarDataMapping, QItemModelScatterDataMapping, and
-    QItemModelSurfaceDataMapping.
+    Depending on the visualization type, proxies may support other functionalities as well,
+    such as QItemModelBarDataProxy optionally mapping QAbstractItemModel rows and columns directly
+    into bar graph rows and columns. See individual proxy classes for more information and examples
+    about how to use them: QItemModelBarDataProxy, QItemModelScatterDataProxy, and
+    QItemModelSurfaceDataProxy.
 
     \section1 Other custom proxies
 
@@ -264,12 +264,9 @@
     \section1 Data selection modes
 
     All visualization types support selecting a single data item - a bar, a scatter item, or a surface
-    vertex - using mouse, touch, and programmatically via the graph APIs. The selected item is highlighted
-    in the rendered graph, and selecting causes emission of a graph specific signal for this purpose,
-    for example, Q3DBars::selectedBarChanged(), which the application can handle.
-
-    \note The surface graph doesn't have a fully implemented selection API yet. It only supports
-    selection with mouse and touch in the technology preview version.
+    vertex - using mouse, touch, and programmatically via the series APIs. The selected item is highlighted
+    in the rendered graph, and selecting causes emission of a series specific signal for this purpose,
+    for example, QBar3DSeries::selectedBarChanged(), which the application can handle.
 
     Bar and surface graphs support slice selection modes, where the selected row or column is drawn
     in a separate viewport as a pseudo-2D graph. This makes it easier to see the actual values of
@@ -277,4 +274,7 @@
 
     Bar graph additionally supports simply highlighting the whole row and/or column of the selected bar
     without opening the slice view.
+
+    When multiple series are added to a graph, selecting an item in one of them will clear the selection
+    on other series.
 */