Doc: Fix \brief and \return commands (Q3dSurface)

Remove property getter docs, because they do not add any info,
and move setter docs to separate entries.

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

2 files changed, 52 insertions, 38 deletions

diff --git a/src/datavisualization/doc/src/qtdatavisualization-qml-surface3d.qdoc b/src/datavisualization/doc/src/qtdatavisualization-qml-surface3d.qdoc
index 0aca2af4..8c465216 100644
--- a/src/datavisualization/doc/src/qtdatavisualization-qml-surface3d.qdoc
+++ b/src/datavisualization/doc/src/qtdatavisualization-qml-surface3d.qdoc
@@ -52,34 +52,34 @@
 
 /*!
   \qmlproperty ValueAxis3D Surface3D::axisX
-  The active X axis.
+  The active x-axis.
 
-  If an axis is not given, a temporary default axis with no labels and automatically adjusting
-  range is created.
+  If an axis is not given, a temporary default axis with no labels and an
+  automatically adjusting range is created.
   This temporary axis is destroyed if another axis is explicitly set to the same orientation.
  */
 
 /*!
   \qmlproperty ValueAxis3D Surface3D::axisY
-  The active Y axis.
+  The active y-axis.
 
-  If an axis is not given, a temporary default axis with no labels and automatically adjusting
-  range is created.
+  If an axis is not given, a temporary default axis with no labels and an
+  automatically adjusting range is created.
   This temporary axis is destroyed if another axis is explicitly set to the same orientation.
  */
 
 /*!
   \qmlproperty ValueAxis3D Surface3D::axisZ
-  The active Z axis.
+  The active z-axis.
 
-  If an axis is not given, a temporary default axis with no labels and automatically adjusting
-  range is created.
+  If an axis is not given, a temporary default axis with no labels and an
+  automatically adjusting range is created.
   This temporary axis is destroyed if another axis is explicitly set to the same orientation.
  */
 
 /*!
  * \qmlproperty Surface3DSeries Surface3D::selectedSeries
- * The selected series or \c null. If \l {QAbstract3DGraph::selectionMode}{selectionMode} has
+ * The selected series or null. If \l {QAbstract3DGraph::selectionMode}{selectionMode} has the
  * \c SelectionMultiSeries flag set, this property holds the series which owns the selected point.
  */
 
@@ -114,5 +114,5 @@
 
 /*!
  * \qmlmethod void Surface3D::removeSeries(Surface3DSeries series)
- * Remove the \a series from the graph.
+ * Removes the \a series from the graph.
  */
diff --git a/src/datavisualization/engine/q3dsurface.cpp b/src/datavisualization/engine/q3dsurface.cpp
index e4fc2221..f3fac1c7 100644
--- a/src/datavisualization/engine/q3dsurface.cpp
+++ b/src/datavisualization/engine/q3dsurface.cpp
@@ -142,7 +142,7 @@ void Q3DSurface::removeSeries(QSurface3DSeries *series)
 }
 
 /*!
- * \return list of series added to this graph.
+ * Returns the list of series added to this graph.
  */
 QList<QSurface3DSeries *> Q3DSurface::seriesList() const
 {
@@ -162,12 +162,18 @@ const Q3DSurfacePrivate *Q3DSurface::dptrc() const
 /*!
  * \property Q3DSurface::axisX
  *
- * The active X-axis. Implicitly calls addAxis() to transfer ownership
- * of the \a axis to this graph.
+ * \brief The active x-axis.
+ */
+
+/*!
+ * Sets \a axis as the active x-axis. Implicitly calls addAxis() to transfer the
+ * ownership of the axis to this graph.
  *
- * If the \a axis is null, a temporary default axis with no labels and automatically adjusting
- * range is created.
- * This temporary axis is destroyed if another \a axis is set explicitly to the same orientation.
+ * If \a axis is null, a temporary default axis with no labels and an
+ * automatically adjusting range is created.
+ *
+ * This temporary axis is destroyed if another axis is set explicitly to the
+ * same orientation.
  *
  * \sa addAxis(), releaseAxis()
  */
@@ -176,9 +182,6 @@ void Q3DSurface::setAxisX(QValue3DAxis *axis)
     dptr()->m_shared->setAxisX(axis);
 }
 
-/*!
- * \return used X-axis.
- */
 QValue3DAxis *Q3DSurface::axisX() const
 {
     return static_cast<QValue3DAxis *>(dptrc()->m_shared->axisX());
@@ -187,12 +190,18 @@ QValue3DAxis *Q3DSurface::axisX() const
 /*!
  * \property Q3DSurface::axisY
  *
- * The active Y-axis. Implicitly calls addAxis() to transfer ownership
- * of the \a axis to this graph.
+ * \brief The active y-axis.
+ */
+
+/*!
+ * Sets \a axis as the active y-axis. Implicitly calls addAxis() to transfer the
+ * ownership of the axis to this graph.
+ *
+ * If \a axis is null, a temporary default axis with no labels and an
+ * automatically adjusting range is created.
  *
- * If the \a axis is null, a temporary default axis with no labels and automatically adjusting
- * range is created.
- * This temporary axis is destroyed if another \a axis is set explicitly to the same orientation.
+ * This temporary axis is destroyed if another axis is set explicitly to the
+ * same orientation.
  *
  * \sa addAxis(), releaseAxis()
  */
@@ -201,9 +210,6 @@ void Q3DSurface::setAxisY(QValue3DAxis *axis)
     dptr()->m_shared->setAxisY(axis);
 }
 
-/*!
- * \return used Y-axis.
- */
 QValue3DAxis *Q3DSurface::axisY() const
 {
     return static_cast<QValue3DAxis *>(dptrc()->m_shared->axisY());
@@ -212,12 +218,18 @@ QValue3DAxis *Q3DSurface::axisY() const
 /*!
  * \property Q3DSurface::axisZ
  *
- * The active Z-axis. Implicitly calls addAxis() to transfer ownership
- * of the \a axis to this graph.
+ * \brief The active z-axis.
+ */
+
+/*!
+ * Sets \a axis as the active z-axis. Implicitly calls addAxis() to transfer the
+ * ownership of the axis to this graph.
+ *
+ * If \a axis is null, a temporary default axis with no labels and an
+ * automatically adjusting range is created.
  *
- * If the \a axis is null, a temporary default axis with no labels and automatically adjusting
- * range is created.
- * This temporary axis is destroyed if another \a axis is set explicitly to the same orientation.
+ * This temporary axis is destroyed if another axis is set explicitly to the
+ * same orientation.
  *
  * \sa addAxis(), releaseAxis()
  */
@@ -226,9 +238,6 @@ void Q3DSurface::setAxisZ(QValue3DAxis *axis)
     dptr()->m_shared->setAxisZ(axis);
 }
 
-/*!
- * \return used Z-axis.
- */
 QValue3DAxis *Q3DSurface::axisZ() const
 {
     return static_cast<QValue3DAxis *>(dptrc()->m_shared->axisZ());
@@ -237,7 +246,9 @@ QValue3DAxis *Q3DSurface::axisZ() const
 /*!
  * \property Q3DSurface::selectedSeries
  *
- * The selected series or \c null. If selectionMode has \c SelectionMultiSeries flag set, this
+ * \brief The selected series or null.
+ *
+ * If selectionMode has \c SelectionMultiSeries set, this
  * property holds the series which owns the selected point.
  */
 QSurface3DSeries *Q3DSurface::selectedSeries() const
@@ -249,6 +260,9 @@ QSurface3DSeries *Q3DSurface::selectedSeries() const
  * \property Q3DSurface::flipHorizontalGrid
  * \since QtDataVisualization 1.2
  *
+ * \brief Whether the horizontal axis grid is displayed on top of the graph
+ * rather than on the bottom.
+ *
  * In some use cases the horizontal axis grid is mostly covered by the surface, so it can be more
  * useful to display the horizontal axis grid on top of the graph rather than on the bottom.
  * A typical use case for this is showing 2D spectrograms using orthoGraphic projection with
@@ -296,7 +310,7 @@ void Q3DSurface::releaseAxis(QValue3DAxis *axis)
 }
 
 /*!
- * \return list of all added axes.
+ * Returns the list of all added axes.
  *
  * \sa addAxis()
  */