Doc: Edit data proxy documentation for grammar and style

Change-Id: Ibf26f40e53e8dab3cea717c6ca55e2568cb747e1
Reviewed-by: Tomi Korpipää <tomi.korpipaa@qt.io>

4 files changed, 249 insertions, 195 deletions

diff --git a/src/datavisualization/data/qabstractdataproxy.cpp b/src/datavisualization/data/qabstractdataproxy.cpp
index fa25bc93..a9703e02 100644
--- a/src/datavisualization/data/qabstractdataproxy.cpp
+++ b/src/datavisualization/data/qabstractdataproxy.cpp
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2016 The Qt Company Ltd.
+** Copyright (C) 2017 The Qt Company Ltd.
 ** Contact: https://www.qt.io/licensing/
 **
 ** This file is part of the Qt Data Visualization module of the Qt Toolkit.
@@ -35,11 +35,14 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION
 /*!
  * \class QAbstractDataProxy
  * \inmodule QtDataVisualization
- * \brief Base class for all QtDataVisualization data proxies.
+ * \brief The QAbstractDataProxy class is a base class for all data
+ * visualization data proxies.
  * \since QtDataVisualization 1.0
  *
- * You use the visualization type specific inherited classes instead of the base class.
- * \sa QBarDataProxy, QScatterDataProxy, QSurfaceDataProxy, {Qt Data Visualization Data Handling}
+ * The following visualization type specific inherited classes are used instead
+ * of the base class: QBarDataProxy, QScatterDataProxy, and QSurfaceDataProxy.
+ *
+ * For more information, see \l{Qt Data Visualization Data Handling}.
  */
 
 /*!
@@ -50,22 +53,21 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION
  * \instantiates QAbstractDataProxy
  * \brief Base type for all QtDataVisualization data proxies.
  *
- * This type is uncreatable, but contains properties that are exposed via subtypes.
- *
- * For AbstractDataProxy enums, see \l{QAbstractDataProxy::DataType}.
+ * This type is uncreatable, but contains properties that are exposed via the
+ * following subtypes: BarDataProxy, ScatterDataProxy, SurfaceDataProxy.
  *
- * \sa BarDataProxy, ScatterDataProxy, SurfaceDataProxy, {Qt Data Visualization Data Handling}
+ * For more information, see \l {Qt Data Visualization Data Handling}.
  */
 
 /*!
  * \qmlproperty AbstractDataProxy.DataType AbstractDataProxy::type
- * The type of the proxy.
+ * The type of the proxy. One of the QAbstractDataProxy::DataType values.
  */
 
 /*!
  * \enum QAbstractDataProxy::DataType
  *
- * Data type of the proxy.
+ * This enum type specifies the data type of the proxy.
  *
  * \value DataTypeNone
  *        No data type.
@@ -87,7 +89,7 @@ QAbstractDataProxy::QAbstractDataProxy(QAbstractDataProxyPrivate *d, QObject *pa
 }
 
 /*!
- * Destroys QAbstractDataProxy.
+ * Deletes the abstract data proxy.
  */
 QAbstractDataProxy::~QAbstractDataProxy()
 {
@@ -96,7 +98,7 @@ QAbstractDataProxy::~QAbstractDataProxy()
 /*!
  * \property QAbstractDataProxy::type
  *
- * \brief The type of the proxy.
+ * \brief The data type of the proxy.
  */
 QAbstractDataProxy::DataType QAbstractDataProxy::type() const
 {
diff --git a/src/datavisualization/data/qbardataproxy.cpp b/src/datavisualization/data/qbardataproxy.cpp
index c5dfe71a..0493543b 100644
--- a/src/datavisualization/data/qbardataproxy.cpp
+++ b/src/datavisualization/data/qbardataproxy.cpp
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2016 The Qt Company Ltd.
+** Copyright (C) 2017 The Qt Company Ltd.
 ** Contact: https://www.qt.io/licensing/
 **
 ** This file is part of the Qt Data Visualization module of the Qt Toolkit.
@@ -35,22 +35,24 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION
 /*!
  * \class QBarDataProxy
  * \inmodule QtDataVisualization
- * \brief Base proxy class for Q3DBars.
+ * \brief The QBarDataProxy class is the data proxy for a 3D bars graph.
  * \since QtDataVisualization 1.0
  *
- * QBarDataProxy handles adding, inserting, changing and removing rows of data.
+ * A bar data proxy handles adding, inserting, changing, and removing rows of
+ * data.
  *
  * The data array is a list of vectors (rows) of QBarDataItem instances.
- * Each row can contain different amount of items or even be null.
+ * Each row can contain a different number of items or even be null.
  *
- * QBarDataProxy takes ownership of all QBarDataRows passed to it, whether directly or
- * in a QBarDataArray container.
- * If you use QBarDataRow pointers to directly modify data after adding the array to the proxy,
- * you must also emit proper signal to make the graph update.
+ * QBarDataProxy takes ownership of all QtDataVisualization::QBarDataRow objects
+ * passed to it, whether directly or in a QtDataVisualization::QBarDataArray container.
+ * If bar data row pointers are used to directly modify data after adding the
+ * array to the proxy, the appropriate signal must be emitted to update the
+ * graph.
  *
  * QBarDataProxy optionally keeps track of row and column labels, which QCategory3DAxis 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.
+ * to show axis labels. The row and column labels are stored in a separate array from the data and
+ * row manipulation methods provide alternate versions that do not 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.
  *
@@ -61,14 +63,14 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION
  * \typedef QtDataVisualization::QBarDataRow
  * \relates QBarDataProxy
  *
- * A vector of \l {QBarDataItem}s.
+ * A vector of \l {QBarDataItem} objects.
  */
 
 /*!
  * \typedef QtDataVisualization::QBarDataArray
  * \relates QBarDataProxy
  *
- * A list of pointers to \l {QBarDataRow}s.
+ * A list of pointers to \l {QBarDataRow} objects.
  */
 
 /*!
@@ -78,13 +80,13 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION
  * \ingroup datavisualization_qml
  * \instantiates QBarDataProxy
  * \inherits AbstractDataProxy
- * \brief Base proxy type for Bars3D.
+ * \brief The data proxy for a 3D bars graph.
  *
  * This type handles adding, inserting, changing, and removing rows of data with Qt Quick 2.
  *
  * This type is uncreatable, but contains properties that are exposed via subtypes.
  *
- * For more complete description, see QBarDataProxy.
+ * For a more complete description, see QBarDataProxy.
  *
  * \sa ItemModelBarDataProxy, {Qt Data Visualization Data Handling}
  */
@@ -99,7 +101,7 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION
  *
  * The optional row labels for the array. Indexes in this array match the row
  * indexes in the data array.
- * If the list is shorter than number of rows, all rows will not get labels.
+ * If the list is shorter than the number of rows, all rows will not get labels.
  */
 
 /*!
@@ -116,7 +118,7 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION
  */
 
 /*!
- * Constructs QBarDataProxy with the given \a parent.
+ * Constructs a bar data proxy with the given \a parent.
  */
 QBarDataProxy::QBarDataProxy(QObject *parent) :
     QAbstractDataProxy(new QBarDataProxyPrivate(this), parent)
@@ -132,7 +134,7 @@ QBarDataProxy::QBarDataProxy(QBarDataProxyPrivate *d, QObject *parent) :
 }
 
 /*!
- * Destroys QBarDataProxy.
+ * Deletes the bar data proxy.
  */
 QBarDataProxy::~QBarDataProxy()
 {
@@ -158,10 +160,11 @@ void QBarDataProxy::resetArray()
 }
 
 /*!
- * Takes ownership of the \a newArray. Clears the existing array if the \a newArray is
- * different from the existing array. If it's the same array, this just triggers arrayReset()
- * signal.
- * Passing null array deletes the old array and creates a new empty array.
+ * Takes ownership of the array \a newArray. Clears the existing array if the
+ * new array differs from it. If the arrays are the same, this function
+ * just triggers the arrayReset() signal.
+ *
+ * Passing a null array deletes the old array and creates a new empty array.
  * Row and column labels are not affected.
  */
 void QBarDataProxy::resetArray(QBarDataArray *newArray)
@@ -172,10 +175,12 @@ void QBarDataProxy::resetArray(QBarDataArray *newArray)
 }
 
 /*!
- * Takes ownership of the \a newArray. Clears the existing array if the \a newArray is
- * different from the existing array. If it's the same array, this just triggers arrayReset()
- * signal.
+ * Takes ownership of the array \a newArray. Clears the existing array if the
+ * new array differs from it. If the arrays are the same, this function
+ * just triggers the arrayReset() signal.
+ *
  * Passing a null array deletes the old array and creates a new empty array.
+ *
  * The \a rowLabels and \a columnLabels lists specify the new labels for rows and columns.
  */
 void QBarDataProxy::resetArray(QBarDataArray *newArray, const QStringList &rowLabels,
@@ -187,8 +192,9 @@ void QBarDataProxy::resetArray(QBarDataArray *newArray, const QStringList &rowLa
 }
 
 /*!
- * Changes existing rows by replacing a row at \a rowIndex with a new \a row. The \a row can be
- * the same as the existing row already stored at the \a rowIndex.
+ * Changes an existing row by replacing the row at the position \a rowIndex
+ * with the new row specified by \a row. The new row can be
+ * the same as the existing row already stored at \a rowIndex.
  * Existing row labels are not affected.
  */
 void QBarDataProxy::setRow(int rowIndex, QBarDataRow *row)
@@ -198,9 +204,10 @@ void QBarDataProxy::setRow(int rowIndex, QBarDataRow *row)
 }
 
 /*!
- * Changes existing rows by replacing a row at \a rowIndex with \a row. The \a row can be
- * the same as the existing row already stored at the \a rowIndex.
- * Changes the row label to the \a label.
+ * Changes an existing row by replacing the row at the position \a rowIndex
+ * with the new row specified by \a row. The new row can be
+ * the same as the existing row already stored at \a rowIndex.
+ * Changes the row label to \a label.
  */
 void QBarDataProxy::setRow(int rowIndex, QBarDataRow *row, const QString &label)
 {
@@ -209,9 +216,10 @@ void QBarDataProxy::setRow(int rowIndex, QBarDataRow *row, const QString &label)
 }
 
 /*!
- * Changes existing rows by replacing a rows starting at \a rowIndex with \a rows.
+ * Changes existing rows by replacing the rows starting at the position
+ * \a rowIndex with the new rows specifies by \a rows.
  * Existing row labels are not affected. The rows in the \a rows array can be
- * the same as the existing rows already stored at the \a rowIndex.
+ * the same as the existing rows already stored at \a rowIndex.
  */
 void QBarDataProxy::setRows(int rowIndex, const QBarDataArray &rows)
 {
@@ -220,9 +228,10 @@ void QBarDataProxy::setRows(int rowIndex, const QBarDataArray &rows)
 }
 
 /*!
- * Changes existing rows by replacing a rows starting at \a rowIndex with \a rows.
+ * Changes existing rows by replacing the rows starting at the position
+ * \a rowIndex with the new rows specifies by \a rows.
  * The row labels are changed to \a labels. The rows in the \a rows array can be
- * the same as the existing rows already stored at the \a rowIndex.
+ * the same as the existing rows already stored at \a rowIndex.
  */
 void QBarDataProxy::setRows(int rowIndex, const QBarDataArray &rows, const QStringList &labels)
 {
@@ -231,7 +240,8 @@ void QBarDataProxy::setRows(int rowIndex, const QBarDataArray &rows, const QStri
 }
 
 /*!
- * Changes a single item at \a rowIndex, \a columnIndex to the \a item.
+ * Changes a single item at the position specified by \a rowIndex and
+ * \a columnIndex to the item \a item.
  */
 void QBarDataProxy::setItem(int rowIndex, int columnIndex, const QBarDataItem &item)
 {
@@ -240,8 +250,9 @@ void QBarDataProxy::setItem(int rowIndex, int columnIndex, const QBarDataItem &i
 }
 
 /*!
- * Changes a single item at \a position to the \a item.
- * The X-value of \a position indicates the row and the Y-value indicates the column.
+ * Changes a single item at the position \a position to the item \a item.
+ * The x-value of \a position indicates the row and the y-value indicates the
+ * column.
  */
 void QBarDataProxy::setItem(const QPoint &position, const QBarDataItem &item)
 {
@@ -249,10 +260,10 @@ void QBarDataProxy::setItem(const QPoint &position, const QBarDataItem &item)
 }
 
 /*!
- * Adds a new \a row to the end of array.
+ * Adds the new row \a row to the end of an array.
  * Existing row labels are not affected.
  *
- * \return index of the added row.
+ * Returns the index of the added row.
  */
 int QBarDataProxy::addRow(QBarDataRow *row)
 {
@@ -263,9 +274,9 @@ int QBarDataProxy::addRow(QBarDataRow *row)
 }
 
 /*!
- * Adds a new \a row with the \a label to the end of array.
+ * Adds a the new row \a row with the label \a label to the end of an array.
  *
- * \return index of the added row.
+ * Returns the index of the added row.
  */
 int QBarDataProxy::addRow(QBarDataRow *row, const QString &label)
 {
@@ -276,10 +287,10 @@ int QBarDataProxy::addRow(QBarDataRow *row, const QString &label)
 }
 
 /*!
- * Adds new \a rows to the end of array.
+ * Adds the new \a rows to the end of an array.
  * Existing row labels are not affected.
  *
- * \return index of the first added row.
+ * Returns the index of the first added row.
  */
 int QBarDataProxy::addRows(const QBarDataArray &rows)
 {
@@ -290,9 +301,9 @@ int QBarDataProxy::addRows(const QBarDataArray &rows)
 }
 
 /*!
- * Adds new \a rows with \a labels to the end of array.
+ * Adds the new \a rows with \a labels to the end of the array.
  *
- * \return index of the first added row.
+ * Returns the index of the first added row.
  */
 int QBarDataProxy::addRows(const QBarDataArray &rows, const QStringList &labels)
 {
@@ -303,10 +314,11 @@ int QBarDataProxy::addRows(const QBarDataArray &rows, const QStringList &labels)
 }
 
 /*!
- * Inserts a new \a row into \a rowIndex.
- * If rowIndex is equal to array size, rows are added to end of the array.
- * Any existing row labels are not affected.
- * \note Row labels array will be out of sync with row array after this call,
+ * Inserts the new row \a row into \a rowIndex.
+ * If \a rowIndex is equal to the array size, the rows are added to the end of
+ * the array.
+ * The existing row labels are not affected.
+ * \note The row labels array will be out of sync with the row array after this call
  *       if there were labeled rows beyond the inserted row.
  */
 void QBarDataProxy::insertRow(int rowIndex, QBarDataRow *row)
@@ -317,8 +329,9 @@ void QBarDataProxy::insertRow(int rowIndex, QBarDataRow *row)
 }
 
 /*!
- * Inserts a new \a row with the \a label into \a rowIndex.
- * If rowIndex is equal to array size, rows are added to end of the array.
+ * Inserts the new row \a row with the label \a label into \a rowIndex.
+ * If \a rowIndex is equal to array size, rows are added to the end of the
+ * array.
  */
 void QBarDataProxy::insertRow(int rowIndex, QBarDataRow *row, const QString &label)
 {
@@ -329,9 +342,9 @@ void QBarDataProxy::insertRow(int rowIndex, QBarDataRow *row, const QString &lab
 
 /*!
  * Inserts new \a rows into \a rowIndex.
- * If rowIndex is equal to array size, rows are added to end of the array.
- * Any existing row labels are not affected.
- * \note Row labels array will be out of sync with row array after this call,
+ * If \a rowIndex is equal to the array size, the rows are added to the end of
+ * the array. The existing row labels are not affected.
+ * \note The row labels array will be out of sync with the row array after this call
  *       if there were labeled rows beyond the inserted rows.
  */
 void QBarDataProxy::insertRows(int rowIndex, const QBarDataArray &rows)
@@ -343,7 +356,8 @@ void QBarDataProxy::insertRows(int rowIndex, const QBarDataArray &rows)
 
 /*!
  * Inserts new \a rows with \a labels into \a rowIndex.
- * If rowIndex is equal to array size, rows are added to end of the array.
+ * If \a rowIndex is equal to the array size, the rows are added to the end of
+ * the array.
  */
 void QBarDataProxy::insertRows(int rowIndex, const QBarDataArray &rows, const QStringList &labels)
 {
@@ -353,11 +367,12 @@ void QBarDataProxy::insertRows(int rowIndex, const QBarDataArray &rows, const QS
 }
 
 /*!
- * Removes \a removeCount rows staring at \a rowIndex. Attempting to remove rows past the end of the
- * array does nothing. If \a removeLabels is true, corresponding row labels are also removed. Otherwise
- * the row labels are not affected.
- * \note If \a removeLabels is false, the row labels array will be out of sync with the row array
- *       if there are labeled rows beyond the removed rows.
+ * Removes the number of rows specified by \a removeCount starting at the
+ * position \a rowIndex. Attempting to remove rows past the end of the
+ * array does nothing. If \a removeLabels is \c true, the corresponding row
+ * labels are also removed. Otherwise, the row labels are not affected.
+ * \note If \a removeLabels is \c false, the row labels array will be out of
+ * sync with the row array if there are labeled rows beyond the removed rows.
  */
 void QBarDataProxy::removeRows(int rowIndex, int removeCount, bool removeLabels)
 {
@@ -421,7 +436,7 @@ void QBarDataProxy::setColumnLabels(const QStringList &labels)
 }
 
 /*!
- * \return pointer to the data array.
+ * Returns the pointer to the data array.
  */
 const QBarDataArray *QBarDataProxy::array() const
 {
@@ -429,8 +444,8 @@ const QBarDataArray *QBarDataProxy::array() const
 }
 
 /*!
- * \return pointer to the row at \a rowIndex. It is guaranteed to be valid only until the next call
- * that modifies data.
+ * Returns the pointer to the row at the position \a rowIndex. It is guaranteed
+ * to be valid only until the next call that modifies data.
  */
 const QBarDataRow *QBarDataProxy::rowAt(int rowIndex) const
 {
@@ -440,7 +455,8 @@ const QBarDataRow *QBarDataProxy::rowAt(int rowIndex) const
 }
 
 /*!
- * \return pointer to the item at \a rowIndex, \a columnIndex. It is guaranteed to be valid only
+ * Returns the pointer to the item at the position specified by \a rowIndex and
+ * \a columnIndex. It is guaranteed to be valid only
  * until the next call that modifies data.
  */
 const QBarDataItem *QBarDataProxy::itemAt(int rowIndex, int columnIndex) const
@@ -453,9 +469,9 @@ const QBarDataItem *QBarDataProxy::itemAt(int rowIndex, int columnIndex) const
 }
 
 /*!
- * \return pointer to the item at \a position. The X-value of \a position indicates the row
- * and the Y-value indicates the column. The item is guaranteed to be valid only
- * until the next call that modifies data.
+ * Returns the pointer to the item at the position \a position. The x-value of
+ * \a position indicates the row and the y-value indicates the column. The item
+ * is guaranteed to be valid only until the next call that modifies data.
  */
 const QBarDataItem *QBarDataProxy::itemAt(const QPoint &position) const
 {
@@ -481,50 +497,57 @@ const QBarDataProxyPrivate *QBarDataProxy::dptrc() const
 /*!
  * \fn void QBarDataProxy::arrayReset()
  *
- * Emitted when data array is reset.
- * If you change the whole array contents without calling resetArray(), you need to
- * emit this signal yourself or the graph won't get updated.
+ * This signal is emitted when the data array is reset.
+ * If the contents of the whole array are changed without calling resetArray(),
+ * this signal needs to be emitted to update the graph.
  */
 
 /*!
  * \fn void QBarDataProxy::rowsAdded(int startIndex, int count)
  *
- * Emitted when rows have been added. Provides \a startIndex and \a count of rows added.
- * If you add rows directly to the array without calling addRow() or addRows(), you
- * need to emit this signal yourself or the graph won't get updated.
+ * This signal is emitted when the number of rows specified by \a count is
+ * added starting at the position \a startIndex.
+ * If rows are added to the array without calling addRow() or addRows(),
+ * this signal needs to be emitted to update the graph.
  */
 
 /*!
  * \fn void QBarDataProxy::rowsChanged(int startIndex, int count)
  *
- * Emitted when rows have changed. Provides \a startIndex and \a count of changed rows.
- * If you change rows directly in the array without calling setRow() or setRows(), you
- * need to emit this signal yourself or the graph won't get updated.
+ * This signal is emitted when the number of rows specified by \a count is
+ * changed starting at the position \a startIndex.
+ * If rows are changed in the array without calling setRow() or setRows(),
+ * this signal needs to be emitted to update the graph.
  */
 
 /*!
  * \fn void QBarDataProxy::rowsRemoved(int startIndex, int count)
  *
- * Emitted when rows have been removed. Provides \a startIndex and \a count of rows removed.
- * Index is the current array size if rows were removed from the end of the array.
- * If you remove rows directly from the array without calling removeRows(), you
- * need to emit this signal yourself or the graph won't get updated.
+ * This signal is emitted when the number of rows specified by \a count is
+ * removed starting at the position \a startIndex.
+ *
+ * The index is the current array size if the rows were removed from the end of
+ * the array. If rows are removed from the array without calling removeRows(),
+ * this signal needs to be emitted to update the graph.
  */
 
 /*!
  * \fn void QBarDataProxy::rowsInserted(int startIndex, int count)
  *
- * Emitted when rows have been inserted. Provides \a startIndex and \a count of inserted rows.
- * If you insert rows directly into the array without calling insertRow() or insertRows(), you
- * need to emit this signal yourself or the graph won't get updated.
+ * This signal is emitted when the number of rows specified by \a count is
+ * inserted at the position \a startIndex.
+ *
+ * If rows are inserted into the array without calling insertRow() or
+ * insertRows(), this signal needs to be emitted to update the graph.
  */
 
 /*!
  * \fn void QBarDataProxy::itemChanged(int rowIndex, int columnIndex)
  *
- * Emitted when an item has changed. Provides \a rowIndex and \a columnIndex of changed item.
- * If you change an item directly in the array without calling setItem(), you
- * need to emit this signal yourself or the graph won't get updated.
+ * This signal is emitted when the item at the position specified by \a rowIndex
+ * and \a columnIndex changes.
+ * If the item is changed in the array without calling setItem(),
+ * this signal needs to be emitted to update the graph.
  */
 
 // QBarDataProxyPrivate
diff --git a/src/datavisualization/data/qscatterdataproxy.cpp b/src/datavisualization/data/qscatterdataproxy.cpp
index 8d1626cf..3d81a641 100644
--- a/src/datavisualization/data/qscatterdataproxy.cpp
+++ b/src/datavisualization/data/qscatterdataproxy.cpp
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2016 The Qt Company Ltd.
+** Copyright (C) 2017 The Qt Company Ltd.
 ** Contact: https://www.qt.io/licensing/
 **
 ** This file is part of the Qt Data Visualization module of the Qt Toolkit.
@@ -36,13 +36,15 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION
 /*!
  * \class QScatterDataProxy
  * \inmodule QtDataVisualization
- * \brief Base proxy class for Q3DScatter.
+ * \brief The QScatterDataProxy class is the data proxy for 3D scatter graphs.
  * \since QtDataVisualization 1.0
  *
- * QScatterDataProxy handles adding, inserting, changing, and removing data items.
+ * A scatter data proxy handles adding, inserting, changing, and removing data
+ * items.
  *
- * QScatterDataProxy takes ownership of all QScatterDataArray and QScatterDataItem
- * objects passed to it.
+ * QScatterDataProxy takes ownership of all
+ * QtDataVisualization::QScatterDataArray and QScatterDataItem objects passed to
+ * it.
  *
  * \sa {Qt Data Visualization Data Handling}
  */
@@ -51,7 +53,7 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION
  * \typedef QtDataVisualization::QScatterDataArray
  * \relates QScatterDataProxy
  *
- * A vector of \l {QScatterDataItem}s.
+ * A vector of \l {QScatterDataItem} objects.
  */
 
 /*!
@@ -61,7 +63,7 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION
  * \ingroup datavisualization_qml
  * \instantiates QScatterDataProxy
  * \inherits AbstractDataProxy
- * \brief Base proxy class for Scatter3D.
+ * \brief The data proxy for 3D scatter graphs.
  *
  * This type handles adding, inserting, changing, and removing data items.
  *
@@ -98,7 +100,7 @@ QScatterDataProxy::QScatterDataProxy(QScatterDataProxyPrivate *d, QObject *paren
 }
 
 /*!
- * Destroys QScatterDataProxy.
+ * Deletes the scatter data proxy.
  */
 QScatterDataProxy::~QScatterDataProxy()
 {
@@ -115,9 +117,10 @@ QScatter3DSeries *QScatterDataProxy::series() const
 }
 
 /*!
- * Takes ownership of the \a newArray. Clears the existing array if the \a newArray is
- * different from the existing array. If it's the same array, this just triggers arrayReset()
- * signal.
+ * Takes ownership of the array \a newArray. Clears the existing array if the
+ * new array differs from it. If the arrays are the same, this function
+ * just triggers the arrayReset() signal.
+ *
  * Passing a null array deletes the old array and creates a new empty array.
  */
 void QScatterDataProxy::resetArray(QScatterDataArray *newArray)
@@ -130,7 +133,7 @@ void QScatterDataProxy::resetArray(QScatterDataArray *newArray)
 }
 
 /*!
- * Changes a single item at \a index with \a item.
+ * Replaces the item at the position \a index with the item \a item.
  */
 void QScatterDataProxy::setItem(int index, const QScatterDataItem &item)
 {
@@ -139,7 +142,8 @@ void QScatterDataProxy::setItem(int index, const QScatterDataItem &item)
 }
 
 /*!
- * Changes items starting from \a index with \a items.
+ * Replaces the items starting from the position \a index with the items
+ * specified by \a items.
  */
 void QScatterDataProxy::setItems(int index, const QScatterDataArray &items)
 {
@@ -148,7 +152,7 @@ void QScatterDataProxy::setItems(int index, const QScatterDataArray &items)
 }
 
 /*!
- * Adds a single \a item to the end of the array.
+ * Adds the item \a item to the end of the array.
  *
  * Returns the index of the added item.
  */
@@ -161,7 +165,7 @@ int QScatterDataProxy::addItem(const QScatterDataItem &item)
 }
 
 /*!
- * Adds \a items to the end of the array.
+ * Adds the items specified by \a items to the end of the array.
  *
  * Returns the index of the first added item.
  */
@@ -174,8 +178,8 @@ int QScatterDataProxy::addItems(const QScatterDataArray &items)
 }
 
 /*!
- * Inserts a single \a item to \a index. If index is equal to data array size, item is added to
- * the array.
+ * Inserts the item \a item to the position \a index. If the index is equal to
+ * the data array size, the item is added to the array.
  */
 void QScatterDataProxy::insertItem(int index, const QScatterDataItem &item)
 {
@@ -185,7 +189,8 @@ void QScatterDataProxy::insertItem(int index, const QScatterDataItem &item)
 }
 
 /*!
- * Inserts \a items to \a index. If index is equal to data array size, items are added to the array.
+ * Inserts the items specified by \a items to the position \a index. If the
+ * index is equal to data array size, the items are added to the array.
  */
 void QScatterDataProxy::insertItems(int index, const QScatterDataArray &items)
 {
@@ -195,7 +200,8 @@ void QScatterDataProxy::insertItems(int index, const QScatterDataArray &items)
 }
 
 /*!
- * Removes \a removeCount items starting from \a index. Attempting to remove items past the end of
+ * Removes the number of items specified by \a removeCount starting at the
+ * position \a index. Attempting to remove items past the end of
  * the array does nothing.
  */
 void QScatterDataProxy::removeItems(int index, int removeCount)
@@ -254,42 +260,46 @@ const QScatterDataProxyPrivate *QScatterDataProxy::dptrc() const
 /*!
  * \fn void QScatterDataProxy::arrayReset()
  *
- * Emitted when data array is reset.
- * If you change the whole array contents without calling resetArray(), you need to
- * emit this signal yourself or the graph won't get updated.
+ * This signal is emitted when the data array is reset.
+ * If the contents of the whole array are changed without calling resetArray(),
+ * this signal needs to be emitted to update the graph.
  */
 
 /*!
  * \fn void QScatterDataProxy::itemsAdded(int startIndex, int count)
  *
- * Emitted when items have been added. Provides \a startIndex and \a count of items added.
- * If you add items directly to the array without calling addItem() or addItems(), you
- * need to emit this signal yourself or the graph won't get updated.
+ * This signal is emitted when the number of items specified by \a count is
+ * added starting at the position \a startIndex.
+ * If items are added to the array without calling addItem() or addItems(),
+ * this signal needs to be emitted to update the graph.
  */
 
 /*!
  * \fn void QScatterDataProxy::itemsChanged(int startIndex, int count)
  *
- * Emitted when items have changed. Provides \a startIndex and \a count of changed items.
- * If you change items directly in the array without calling setItem() or setItems(), you
- * need to emit this signal yourself or the graph won't get updated.
+ * This signal is emitted when the number of items specified by \a count is
+ * changed starting at the position \a startIndex.
+ * If items are changed in the array without calling setItem() or setItems(),
+ * this signal needs to be emitted to update the graph.
  */
 
 /*!
  * \fn void QScatterDataProxy::itemsRemoved(int startIndex, int count)
  *
- * Emitted when items have been removed. Provides \a startIndex and \a count of items removed.
- * Index may be over current array size if removed from end.
- * If you remove items directly from the array without calling removeItems(), you
- * need to emit this signal yourself or the graph won't get updated.
+ * This signal is emitted when the number of rows specified by \a count is
+ * removed starting at the position \a startIndex.
+ * The index may be larger than the current array size if items are removed from
+ * the end. If items are removed from the array without calling removeItems(),
+ * this signal needs to be emitted to update the graph.
  */
 
 /*!
  * \fn void QScatterDataProxy::itemsInserted(int startIndex, int count)
  *
- * Emitted when items have been inserted. Provides \a startIndex and \a count of inserted items.
- * If you insert items directly into the array without calling insertItem() or insertItems(), you
- * need to emit this signal yourself or the graph won't get updated.
+ * This signal is emitted when the number of items specified by \a count is
+ * inserted starting at the position \a startIndex.
+ * If items are inserted into the array without calling insertItem() or
+ * insertItems(), this signal needs to be emitted to update the graph.
  */
 
 // QScatterDataProxyPrivate
diff --git a/src/datavisualization/data/qsurfacedataproxy.cpp b/src/datavisualization/data/qsurfacedataproxy.cpp
index 61abbe58..a5339e9d 100644
--- a/src/datavisualization/data/qsurfacedataproxy.cpp
+++ b/src/datavisualization/data/qsurfacedataproxy.cpp
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2016 The Qt Company Ltd.
+** Copyright (C) 2017 The Qt Company Ltd.
 ** Contact: https://www.qt.io/licensing/
 **
 ** This file is part of the Qt Data Visualization module of the Qt Toolkit.
@@ -36,38 +36,41 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION
 /*!
  * \class QSurfaceDataProxy
  * \inmodule QtDataVisualization
- * \brief Base proxy class for Q3DSurface.
+ * \brief The QSurfaceDataProxy class is the data proxy for a 3D surface graph.
  * \since QtDataVisualization 1.0
  *
- * QSurfaceDataProxy takes care of surface related data handling. The QSurfaceDataProxy handles the
- * data in rows and for this it provides two auxiliary typedefs. QSurfaceDataArray is a QList for
- * controlling the rows. For rows there is a QVector QSurfaceDataRow which contains QSurfaceDataItem
- * objects. See Q3DSurface documentation and basic sample code there how to feed the data for the
- * QSurfaceDataProxy.
+ * A surface data proxy handles surface related data in rows. For this it
+ * provides two auxiliary typedefs: QtDataVisualization::QSurfaceDataArray and
+ * QtDataVisualization::QSurfaceDataRow. \c QSurfaceDataArray is a QList that
+ * controls the rows. \c QSurfaceDataRow is a QVector that contains
+ * QSurfaceDataItem objects. For more information about how to feed the data to
+ * the proxy, see the sample code in the Q3DSurface documentation.
  *
  * All rows must have the same number of items.
  *
- * QSurfaceDataProxy takes ownership of all QSurfaceDataRows passed to it, whether directly or
- * in a QSurfaceDataArray container.
- * If you use QSurfaceDataRow pointers to directly modify data after adding the array to the proxy,
- * you must also emit proper signal to make the graph update.
+ * QSurfaceDataProxy takes ownership of all \c QSurfaceDataRow objects passed to
+ * it, whether directly or in a \c QSurfaceDataArray container.
+ * To use surface data row pointers to directly modify data after adding the
+ * array to the proxy, the appropriate signal must be emitted to update the
+ * graph.
  *
- * To make a sensible surface, the X-value of each successive item in all rows must be
+ * To make a sensible surface, the x-value of each successive item in all rows must be
  * either ascending or descending throughout the row.
- * Similarly, the Z-value of each successive item in all columns must be either ascending or
+ * Similarly, the z-value of each successive item in all columns must be either ascending or
  * descending throughout the column.
  *
  * \note Currently only surfaces with straight rows and columns are fully supported. Any row
- * with items that do not have the exact same Z-value or any column with items that do not have
- * the exact same X-value may get clipped incorrectly if the whole surface doesn't completely fit
- * in the visible X or Z axis ranges.
+ * with items that do not have the exact same z-value or any column with items
+ * that do not have the exact same x-value may get clipped incorrectly if the
+ * whole surface does not completely fit within the visible x-axis or z-axis
+ * ranges.
  *
  * \note Surfaces with less than two rows or columns are not considered valid surfaces and will
  * not be rendered.
  *
  * \note On some environments, surfaces with a lot of visible vertices may not render, because
  * they exceed the per-draw vertex count supported by the graphics driver.
- * This is mostly an issue on 32bit and/or OpenGL ES2 platforms.
+ * This is mostly an issue on 32-bit and OpenGL ES2 platforms.
  *
  * \sa {Qt Data Visualization Data Handling}
  */
@@ -76,14 +79,14 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION
  * \typedef QtDataVisualization::QSurfaceDataRow
  * \relates QSurfaceDataProxy
  *
- * A vector of \l {QSurfaceDataItem}s.
+ * A vector of \l {QSurfaceDataItem} objects.
  */
 
 /*!
  * \typedef QtDataVisualization::QSurfaceDataArray
  * \relates QSurfaceDataProxy
  *
- * A list of pointers to \l {QSurfaceDataRow}s.
+ * A list of pointers to \l {QSurfaceDataRow} objects.
  */
 
 /*!
@@ -93,7 +96,7 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION
  * \ingroup datavisualization_qml
  * \instantiates QSurfaceDataProxy
  * \inherits AbstractDataProxy
- * \brief Base proxy class for Surface3D.
+ * \brief The data proxy for a 3D surface graph.
  *
  * This type handles surface data items. The data is arranged into rows and columns, and all rows must have
  * the same number of columns.
@@ -138,7 +141,7 @@ QSurfaceDataProxy::QSurfaceDataProxy(QSurfaceDataProxyPrivate *d, QObject *paren
 }
 
 /*!
- * Destroys QSurfaceDataProxy.
+ * Deletes the surface data proxy.
  */
 QSurfaceDataProxy::~QSurfaceDataProxy()
 {
@@ -155,9 +158,10 @@ QSurface3DSeries *QSurfaceDataProxy::series() const
 }
 
 /*!
- * Takes ownership of the \a newArray. Clears the existing array if the \a newArray is
- * different from the existing array. If it's the same array, this just triggers arrayReset()
- * signal.
+ * Takes ownership of the array \a newArray. Clears the existing array if the
+ * new array differs from it. If the arrays are the same, this function
+ * just triggers the arrayReset() signal.
+ *
  * Passing a null array deletes the old array and creates a new empty array.
  * All rows in \a newArray must be of same length.
  */
@@ -172,8 +176,9 @@ void QSurfaceDataProxy::resetArray(QSurfaceDataArray *newArray)
 }
 
 /*!
- * Changes existing row by replacing a row at \a rowIndex with a new \a row. The \a row can be
- * the same as the existing row already stored at the \a rowIndex. The new \a row must have
+ * Changes an existing row by replacing the row at the position \a rowIndex
+ * with the new row specified by \a row. The new row can be the same as the
+ * existing row already stored at the \a rowIndex. The new row must have
  * the same number of columns as the row it is replacing.
  */
 void QSurfaceDataProxy::setRow(int rowIndex, QSurfaceDataRow *row)
@@ -183,7 +188,8 @@ void QSurfaceDataProxy::setRow(int rowIndex, QSurfaceDataRow *row)
 }
 
 /*!
- * Changes existing rows by replacing a rows starting at \a rowIndex with \a rows.
+ * Changes existing rows by replacing the rows starting at the position
+ * \a rowIndex with the new rows specifies by \a rows.
  * The rows in the \a rows array can be the same as the existing rows already
  * stored at the \a rowIndex. The new rows must have the same number of columns
  * as the rows they are replacing.
@@ -195,7 +201,8 @@ void QSurfaceDataProxy::setRows(int rowIndex, const QSurfaceDataArray &rows)
 }
 
 /*!
- * Changes a single item at \a rowIndex, \a columnIndex to the \a item.
+ * Changes a single item at the position specified by \a rowIndex and
+ * \a columnIndex to the item \a item.
  */
 void QSurfaceDataProxy::setItem(int rowIndex, int columnIndex, const QSurfaceDataItem &item)
 {
@@ -204,8 +211,9 @@ void QSurfaceDataProxy::setItem(int rowIndex, int columnIndex, const QSurfaceDat
 }
 
 /*!
- * Changes a single item at \a position to the \a item.
- * The X-value of \a position indicates the row and the Y-value indicates the column.
+ * Changes a single item at the position \a position to the item \a item.
+ * The x-value of \a position indicates the row and the y-value indicates the
+ * column.
  */
 void QSurfaceDataProxy::setItem(const QPoint &position, const QSurfaceDataItem &item)
 {
@@ -213,8 +221,8 @@ void QSurfaceDataProxy::setItem(const QPoint &position, const QSurfaceDataItem &
 }
 
 /*!
- * Adds a new \a row to the end of array. The new \a row must have
- * the same number of columns as the rows at the initial array.
+ * Adds the new row \a row to the end of an array. The new row must have
+ * the same number of columns as the rows in the initial array.
  *
  * Returns the index of the added row.
  */
@@ -227,8 +235,8 @@ int QSurfaceDataProxy::addRow(QSurfaceDataRow *row)
 }
 
 /*!
- * Adds new \a rows to the end of array. The new rows must have the same number of columns
- * as the rows at the initial array.
+ * Adds new \a rows to the end of an array. The new rows must have the same
+ * number of columns as the rows in the initial array.
  *
  * Returns the index of the first added row.
  */
@@ -241,9 +249,10 @@ int QSurfaceDataProxy::addRows(const QSurfaceDataArray &rows)
 }
 
 /*!
- * Inserts a new \a row into \a rowIndex.
- * If rowIndex is equal to array size, rows are added to end of the array. The new \a row must have
- * the same number of columns as the rows at the initial array.
+ * Inserts the new row \a row into \a rowIndex.
+ * If \a rowIndex is equal to the array size, the rows are added to the end of
+ * the array. The new row must have the same number of columns as the rows in
+ * the initial array.
  */
 void QSurfaceDataProxy::insertRow(int rowIndex, QSurfaceDataRow *row)
 {
@@ -254,8 +263,9 @@ void QSurfaceDataProxy::insertRow(int rowIndex, QSurfaceDataRow *row)
 
 /*!
  * Inserts new \a rows into \a rowIndex.
- * If rowIndex is equal to array size, rows are added to end of the array. The new \a rows must have
- * the same number of columns as the rows at the initial array.
+ * If \a rowIndex is equal to the array size, the rows are added to the end of
+ * the array. The new \a rows must have the same number of columns as the rows
+ * in the initial array.
  */
 void QSurfaceDataProxy::insertRows(int rowIndex, const QSurfaceDataArray &rows)
 {
@@ -265,7 +275,8 @@ void QSurfaceDataProxy::insertRows(int rowIndex, const QSurfaceDataArray &rows)
 }
 
 /*!
- * Removes \a removeCount rows staring at \a rowIndex. Attempting to remove rows past the end of the
+ * Removes the number of rows specified by \a removeCount starting at the
+ * position \a rowIndex. Attempting to remove rows past the end of the
  * array does nothing.
  */
 void QSurfaceDataProxy::removeRows(int rowIndex, int removeCount)
@@ -286,7 +297,8 @@ const QSurfaceDataArray *QSurfaceDataProxy::array() const
 }
 
 /*!
- * Returns the pointer to the item at \a rowIndex, \a columnIndex. It is guaranteed to be valid only
+ * Returns the pointer to the item at the position specified by \a rowIndex and
+ * \a columnIndex. It is guaranteed to be valid only
  * until the next call that modifies data.
  */
 const QSurfaceDataItem *QSurfaceDataProxy::itemAt(int rowIndex, int columnIndex) const
@@ -299,9 +311,9 @@ const QSurfaceDataItem *QSurfaceDataProxy::itemAt(int rowIndex, int columnIndex)
 }
 
 /*!
- * Returns the pointer to the item at \a position. The X-value of \a position indicates the row
- * and the Y-value indicates the column. The item is guaranteed to be valid only
- * until the next call that modifies data.
+ * Returns the pointer to the item at the position \a position. The x-value of
+ * \a position indicates the row and the y-value indicates the column. The item
+ * is guaranteed to be valid only until the next call that modifies data.
  */
 const QSurfaceDataItem *QSurfaceDataProxy::itemAt(const QPoint &position) const
 {
@@ -350,50 +362,57 @@ const QSurfaceDataProxyPrivate *QSurfaceDataProxy::dptrc() const
 /*!
  * \fn void QSurfaceDataProxy::arrayReset()
  *
- * Emitted when the data array is reset.
- * If you change the whole array contents without calling resetArray(), you need to
- * emit this signal yourself or the graph won't get updated.
+ * This signal is emitted when the data array is reset.
+ * If the contents of the whole array are changed without calling resetArray(),
+ * this signal needs to be emitted to update the graph.
  */
 
 /*!
  * \fn void QSurfaceDataProxy::rowsAdded(int startIndex, int count)
  *
- * Emitted when rows have been added. Provides \a startIndex and \a count of rows added.
- * If you add rows directly to the array without calling addRow() or addRows(), you
- * need to emit this signal yourself or the graph won't get updated.
+ * This signal is emitted when the number of rows specified by \a count is
+ * added starting at the position \a startIndex.
+ * If rows are added to the array without calling addRow() or addRows(),
+ * this signal needs to be emitted to update the graph.
  */
 
 /*!
  * \fn void QSurfaceDataProxy::rowsChanged(int startIndex, int count)
  *
- * Emitted when rows have changed. Provides \a startIndex and \a count of changed rows.
- * If you change rows directly in the array without calling setRow() or setRows(), you
- * need to emit this signal yourself or the graph won't get updated.
+ * This signal is emitted when the number of rows specified by \a count is
+ * changed starting at the position \a startIndex.
+ * If rows are changed in the array without calling setRow() or setRows(),
+ * this signal needs to be emitted to update the graph.
  */
 
 /*!
  * \fn void QSurfaceDataProxy::rowsRemoved(int startIndex, int count)
  *
- * Emitted when rows have been removed. Provides \a startIndex and \a count of rows removed.
- * Index is the current array size if rows were removed from the end of the array.
- * If you remove rows directly from the array without calling removeRows(), you
- * need to emit this signal yourself or the graph won't get updated.
+ * This signal is emitted when the number of rows specified by \a count is
+ * removed starting at the position \a startIndex.
+ *
+ * The index is the current array size if the rows were removed from the end of
+ * the array. If rows are removed from the array without calling removeRows(),
+ * this signal needs to be emitted to update the graph.
  */
 
 /*!
  * \fn void QSurfaceDataProxy::rowsInserted(int startIndex, int count)
  *
- * Emitted when rows have been inserted. Provides \a startIndex and \a count of inserted rows.
- * If you insert rows directly into the array without calling insertRow() or insertRows(), you
- * need to emit this signal yourself or the graph won't get updated.
+ * This signal is emitted when the number of rows specified by \a count is
+ * inserted at the position \a startIndex.
+ *
+ * If rows are inserted into the array without calling insertRow() or
+ * insertRows(), this signal needs to be emitted to update the graph.
  */
 
 /*!
  * \fn void QSurfaceDataProxy::itemChanged(int rowIndex, int columnIndex)
  *
- * Emitted when an item has changed. Provides \a rowIndex and \a columnIndex of changed item.
- * If you change an item directly in the array without calling setItem(), you
- * need to emit this signal yourself or the graph won't get updated.
+ * This signal is emitted when the item at the position specified by \a rowIndex
+ * and \a columnIndex changes.
+ * If the item is changed in the array without calling setItem(),
+ * this signal needs to be emitted to update the graph.
  */
 
 //  QSurfaceDataProxyPrivate