Doc: Edit the axes documentation for grammar and style

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

5 files changed, 157 insertions, 135 deletions

diff --git a/src/datavisualization/axis/qabstract3daxis.cpp b/src/datavisualization/axis/qabstract3daxis.cpp
index 90f93eb9..72754ac8 100644
--- a/src/datavisualization/axis/qabstract3daxis.cpp
+++ b/src/datavisualization/axis/qabstract3daxis.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.
@@ -34,10 +34,12 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION
 /*!
  * \class QAbstract3DAxis
  * \inmodule QtDataVisualization
- * \brief QAbstract3DAxis is base class for axes of a graph.
+ * \brief The QAbstract3DAxis class is a base class for the axes of a graph.
  * \since QtDataVisualization 1.0
  *
- * You should not need to use this class directly, but one of its subclasses instead.
+ * This class specifies the enumerations, properties, and functions shared by
+ * graph axes. It should not be used directly, but one of its subclasses should
+ * be used instead.
  *
  * \sa QCategory3DAxis, QValue3DAxis
  */
@@ -48,7 +50,7 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION
  * \since QtDataVisualization 1.0
  * \ingroup datavisualization_qml
  * \instantiates QAbstract3DAxis
- * \brief AbstractAxis3D is base type for axes of a graph.
+ * \brief A base type for the axes of a graph.
  *
  * This type is uncreatable, but contains properties that are exposed via subtypes.
  *
@@ -83,16 +85,16 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION
  * \qmlproperty real AbstractAxis3D::min
  *
  * The minimum value on the axis.
- * When setting this property the max is adjusted if necessary, to ensure that the range remains
- * valid.
+ * When setting this property, the maximum value is adjusted if necessary, to
+ * ensure that the range remains valid.
  */
 
 /*!
  * \qmlproperty real AbstractAxis3D::max
  *
  * The maximum value on the axis.
- * When setting this property the min is adjusted if necessary, to ensure that the range remains
- * valid.
+ * When setting this property, the minimum value is adjusted if necessary, to
+ * ensure that the range remains valid.
  */
 
 /*!
@@ -130,7 +132,8 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION
  * to the axis labels.
  * If \c{false}, axis titles are only rotated around their axis but are not otherwise oriented
  * towards the camera.
- * This property doesn't have any effect if labelAutoRotation property value is zero.
+ * This property does not have any effect if the labelAutoRotation property
+ * value is zero.
  * Default value is \c{true}.
  *
  * \sa labelAutoRotation, title, titleVisible
@@ -235,9 +238,11 @@ QStringList QAbstract3DAxis::labels() const
 }
 
 /*!
- * Sets value range of the axis from \a min to \a max.
- * When setting the range, the max is adjusted if necessary, to ensure that the range remains valid.
- * \note For QCategory3DAxis this specifies the index range of rows or columns to show.
+ * Sets the value range of the axis from \a min to \a max.
+ * When setting the range, the maximum value is adjusted if necessary, to ensure
+ * that the range remains valid.
+ * \note For QCategory3DAxis, specifies the index range of rows or columns to
+ * show.
  */
 void QAbstract3DAxis::setRange(float min, float max)
 {
@@ -303,7 +308,8 @@ bool QAbstract3DAxis::isTitleVisible() const
  * to the axis labels.
  * If \c{false}, axis titles are only rotated around their axis but are not otherwise oriented
  * towards the camera.
- * This property doesn't have any effect if labelAutoRotation property value is zero.
+ * This property does not have any effect if the labelAutoRotation property
+ * value is zero.
  * Default value is \c{true}.
  *
  * \sa labelAutoRotation, title, titleVisible
@@ -326,9 +332,10 @@ bool QAbstract3DAxis::isTitleFixed() const
  *
  * \brief The minimum value on the axis.
  *
- * When setting this property the max is adjusted if necessary, to ensure that the range remains
- * valid.
- * \note For QCategory3DAxis this specifies the index of the first row or column to show.
+ * When setting this property, the maximum value is adjusted if necessary, to
+ * ensure that the range remains valid.
+ * \note For QCategory3DAxis, specifies the index of the first row or column to
+ * show.
  */
 void QAbstract3DAxis::setMin(float min)
 {
@@ -341,9 +348,10 @@ void QAbstract3DAxis::setMin(float min)
  *
  * \brief The maximum value on the axis.
  *
- * When setting this property the min is adjusted if necessary, to ensure that the range remains
- * valid.
- * \note For QCategory3DAxis this specifies the index of the last row or column to show.
+ * When setting this property, the minimum value is adjusted if necessary, to
+ * ensure that the range remains valid.
+ * \note For QCategory3DAxis, specifies the index of the last row or column to
+ * show.
  */
 void QAbstract3DAxis::setMax(float max)
 {
@@ -384,7 +392,8 @@ bool QAbstract3DAxis::isAutoAdjustRange() const
 /*!
  * \fn QAbstract3DAxis::rangeChanged(float min, float max)
  *
- * Emits range \a min and \a max values when range changes.
+ * Emits the minimum and maximum values of the range, \a min and \a max, when
+ * the range changes.
  */
 
 // QAbstract3DAxisPrivate
diff --git a/src/datavisualization/axis/qcategory3daxis.cpp b/src/datavisualization/axis/qcategory3daxis.cpp
index faf286ab..17bfe490 100644
--- a/src/datavisualization/axis/qcategory3daxis.cpp
+++ b/src/datavisualization/axis/qcategory3daxis.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,7 +35,7 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION
 /*!
  * \class QCategory3DAxis
  * \inmodule QtDataVisualization
- * \brief The QCategory3DAxis class is used for manipulating an axis of a graph.
+ * \brief The QCategory3DAxis class manipulates an axis of a graph.
  * \since QtDataVisualization 1.0
  *
  * QCategory3DAxis provides an axis that can be given labels. The axis is divided into equal-sized
@@ -52,7 +52,7 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION
  * \ingroup datavisualization_qml
  * \instantiates QCategory3DAxis
  * \inherits AbstractAxis3D
- * \brief The CategoryAxis3D type is used for manipulating an axis of a graph.
+ * \brief Manipulates an axis of a graph.
  *
  * This type provides an axis that can be given labels.
  */
@@ -66,7 +66,7 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION
  */
 
 /*!
- * Constructs QCategory3DAxis with \a parent.
+ * Constructs a category 3D axis with the parent \a parent.
  */
 QCategory3DAxis::QCategory3DAxis(QObject *parent) :
     QAbstract3DAxis(new QCategory3DAxisPrivate(this), parent)
@@ -75,7 +75,7 @@ QCategory3DAxis::QCategory3DAxis(QObject *parent) :
 }
 
 /*!
- * Destroys QCategory3DAxis.
+ * Destroys the category 3D axis.
  */
 QCategory3DAxis::~QCategory3DAxis()
 {
diff --git a/src/datavisualization/axis/qlogvalue3daxisformatter.cpp b/src/datavisualization/axis/qlogvalue3daxisformatter.cpp
index fb1e7447..3e044ed5 100644
--- a/src/datavisualization/axis/qlogvalue3daxisformatter.cpp
+++ b/src/datavisualization/axis/qlogvalue3daxisformatter.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,12 +36,11 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION
 /*!
  * \class QLogValue3DAxisFormatter
  * \inmodule QtDataVisualization
- * \brief QLogValue3DAxisFormatter implements logarithmic value axis formatter.
+ * \brief The QLogValue3DAxisFormatter class provides formatting rules for a
+ * logarithmic value axis.
  * \since QtDataVisualization 1.1
  *
- * This class provides formatting rules for a logarithmic QValue3DAxis.
- *
- * When a QLogValue3DAxisFormatter is attached to a QValue3DAxis, the axis range
+ * When a formatter is attached to a value axis, the axis range
  * cannot include negative values or the zero.
  *
  * \sa QValue3DAxisFormatter
@@ -54,10 +53,9 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION
  * \ingroup datavisualization_qml
  * \instantiates QLogValue3DAxisFormatter
  * \inherits ValueAxis3DFormatter
- * \brief LogValueAxis3DFormatter implements logarithmic value axis formatter.
+ * \brief Provides formatting rules for a logarithmic value axis.
  *
- * This type provides formatting rules for a logarithmic ValueAxis3D.
- * When a LogValueAxis3DFormatter is attached to a ValueAxis3D, the axis range
+ * When a formatter is attached to a value axis, the axis range
  * cannot include negative values or the zero.
  */
 
@@ -66,10 +64,10 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION
  *
  * The base of the logarithm used to map axis values. If the base is non-zero, the parent axis
  * segment count will be ignored when the grid line and label positions are calculated.
- * If you want the range to be divided into equal segments like normal value axis, set this
+ * If you want the range to be divided into equal segments like a normal value axis, set this
  * property value to zero.
  *
- * The base has to be zero or positive value and not equal to one.
+ * The base has to be zero or a positive value and it cannot be equal to one.
  * Defaults to ten.
  *
  * \sa ValueAxis3D::segmentCount
@@ -82,9 +80,9 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION
  *
  * If this property value is set to \c true, the parent axis sub-segment count is ignored
  * when calculating sub-grid line positions. The sub-grid positions are generated automatically
- * according to the base property value.
- * The number of sub-grid lines is set to base value minus one, rounded down.
- * This property is ignored when base property value is zero.
+ * according to the \l base property value.
+ * The number of sub-grid lines is set to the base value minus one, rounded down.
+ * This property is ignored when the base value is zero.
  * Defaults to \c true.
  *
  * \sa base, ValueAxis3D::subSegmentCount
@@ -95,9 +93,10 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION
  *
  * Defines whether the first and last label on the axis are visible.
  *
- * When the base property value is non-zero, the whole axis range is often not equally divided into
+ * When the \l base property value is non-zero, the whole axis range is often
+ * not equally divided into
  * segments. The first and last segments are often smaller than the other segments.
- * In extreme cases this can lead to overlapping labels on the first and last two grid lines.
+ * In extreme cases, this can lead to overlapping labels on the first and last two grid lines.
  * By setting this property to \c false, you can suppress showing the minimum and maximum labels
  * for the axis in cases where the segments do not exactly fit the axis.
  * Defaults to \c true.
@@ -117,7 +116,8 @@ QLogValue3DAxisFormatter::QLogValue3DAxisFormatter(QLogValue3DAxisFormatterPriva
 }
 
 /*!
- * Constructs a new QLogValue3DAxisFormatter instance with optional \a parent.
+ * Constructs a new logarithmic value 3D axis formatter with the optional
+ * parent \a parent.
  */
 QLogValue3DAxisFormatter::QLogValue3DAxisFormatter(QObject *parent) :
     QValue3DAxisFormatter(new QLogValue3DAxisFormatterPrivate(this), parent)
@@ -127,7 +127,7 @@ QLogValue3DAxisFormatter::QLogValue3DAxisFormatter(QObject *parent) :
 }
 
 /*!
- * Destroys QLogValue3DAxisFormatter.
+ * Deletes the logarithmic value 3D axis formatter.
  */
 QLogValue3DAxisFormatter::~QLogValue3DAxisFormatter()
 {
@@ -140,10 +140,10 @@ QLogValue3DAxisFormatter::~QLogValue3DAxisFormatter()
  *
  * If the base is non-zero, the parent axis
  * segment count will be ignored when the grid line and label positions are calculated.
- * If you want the range to be divided into equal segments like normal value axis, set this
+ * If you want the range to be divided into equal segments like a normal value axis, set this
  * property value to zero.
  *
- * The base has to be zero or positive value and not equal to one.
+ * The base has to be zero or a positive value and it cannot be equal to one.
  * Defaults to ten.
  *
  * \sa QValue3DAxis::segmentCount
@@ -174,9 +174,9 @@ qreal QLogValue3DAxisFormatter::base() const
  *
  * If this property value is set to \c true, the parent axis sub-segment count is ignored
  * when calculating sub-grid line positions. The sub-grid positions are generated automatically
- * according to the base property value.
- * The number of sub-grid lines is set to base value minus one, rounded down.
- * This property is ignored when base property value is zero.
+ * according to the \l base property value. The number of sub-grid lines is set
+ * to the base value minus one, rounded down. This property is ignored when the
+ * base value is zero.
  * Defaults to \c true.
  *
  * \sa base, QValue3DAxis::subSegmentCount
@@ -200,9 +200,10 @@ bool QLogValue3DAxisFormatter::autoSubGrid() const
  *
  * \brief Whether the first and last label on the axis are visible.
  *
- * When the base property value is non-zero, the whole axis range is often not equally divided into
+ * When the \l base property value is non-zero, the whole axis range is often
+ * not equally divided into
  * segments. The first and last segments are often smaller than the other segments.
- * In extreme cases this can lead to overlapping labels on the first and last two grid lines.
+ * In extreme cases, this can lead to overlapping labels on the first and last two grid lines.
  * By setting this property to \c false, you can suppress showing the minimum and maximum labels
  * for the axis in cases where the segments do not exactly fit the axis.
  * Defaults to \c true.
diff --git a/src/datavisualization/axis/qvalue3daxis.cpp b/src/datavisualization/axis/qvalue3daxis.cpp
index efdf7143..f0a72ed4 100644
--- a/src/datavisualization/axis/qvalue3daxis.cpp
+++ b/src/datavisualization/axis/qvalue3daxis.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,10 +36,10 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION
 /*!
  * \class QValue3DAxis
  * \inmodule QtDataVisualization
- * \brief The QValue3DAxis class is used for manipulating an axis of a graph.
+ * \brief The QValue3DAxis class manipulates an axis of a graph.
  * \since QtDataVisualization 1.0
  *
- * QValue3DAxis provides an axis that can be given a range of values and segment and subsegment
+ * A value axis can be given a range of values and segment and subsegment
  * counts to divide the range into.
  *
  * Labels are drawn between each segment. Grid lines are drawn between each segment and each
@@ -54,7 +54,7 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION
  * \ingroup datavisualization_qml
  * \instantiates QValue3DAxis
  * \inherits AbstractAxis3D
- * \brief The ValueAxis3D type is used for manipulating an axis of a graph.
+ * \brief Manipulates an axis of a graph.
  *
  * This type provides an axis that can be given a range of values and segment and subsegment
  * counts to divide the range into.
@@ -65,8 +65,9 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION
  * \qmlproperty int ValueAxis3D::segmentCount
  *
  * The number of segments on the axis. This indicates how many labels are drawn. The number
- * of grid lines to be drawn is calculated with formula: \c {segments * subsegments + 1}.
- * The preset default is \c 5, and it can not be below \c 1.
+ * of grid lines to be drawn is calculated with the following formula:
+ * \c {segments * subsegments + 1}.
+ * The preset default is \c 5. The value cannot be below \c 1.
  */
 
 /*!
@@ -74,20 +75,22 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION
  *
  * The number of subsegments inside each segment on the axis. Grid lines are drawn between
  * each subsegment, in addition to each segment.
- * The preset default is \c 1, and it can not be below \c 1.
+ * The preset default is \c 1. The value cannot be below \c 1.
  */
 
 /*!
  * \qmlproperty string ValueAxis3D::labelFormat
  *
- * The label format to be used for the labels on this axis. How the format is interpreted
- * depends on the axis formatter and the locale in use. Using the default formatter and default
- * locale (\c{"C"}), the formatting uses QString::sprintf(). Supported specifiers are:
- * \c {d, i, o, x, X, f, F, e, E, g, G, c}. See QString::sprintf() for additional details.
- * For other locales, the default formatter uses reduced set of printf format specifiers:
- * \c {d, i, f, F, e, E, g, G}. In these cases, the only supported modifier is the precision
- * modifier for the floating point and exponential formats. The decimal point and other locale
- * dependent formatting is done according to the graph locale.
+ * The label format to be used for the labels on this axis.
+ *
+ * The format string supports the following conversion specifiers, length
+ * modifiers, and flags provided by \c printf() in the standard C++ library:
+ * d, i, o, x, X, f, F, e, E, g, G, c.
+ *
+ * If AbstractGraph3D::locale is anything else than \c{"C"}, the supported
+ * specifiers are limited to: d, e, E, f, g, G, and i. Also, only the precision
+ * modifier is supported. The rest of the formatting comes from the default
+ * \l Locale of the application.
  *
  * \sa AbstractGraph3D::locale
  */
@@ -105,9 +108,9 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION
  * \qmlproperty bool ValueAxis3D::reversed
  * \since QtDataVisualization 1.1
  *
- * If \c{true}, the axis will be rendered in reverse, i.e. the positions of minimum and maximum
- * values are swapped when the graph is rendered. This property doesn't affect the actual
- * minimum and maximum values of the axis.
+ * If \c{true}, the axis will be rendered in reverse. That is, the positions of
+ * the minimum and maximum values are swapped when the graph is rendered. This
+ * property does not affect the actual minimum and maximum values of the axis.
  */
 
 /*!
@@ -133,7 +136,7 @@ QValue3DAxis::~QValue3DAxis()
  *
  * This indicates how many labels are drawn. The number
  * of grid lines to be drawn is calculated with formula: \c {segments * subsegments + 1}.
- * The preset default is \c 5, and it can not be below \c 1.
+ * The preset default is \c 5. The value cannot be below \c 1.
  *
  * \sa setSubSegmentCount()
  */
@@ -163,7 +166,7 @@ int QValue3DAxis::segmentCount() const
  *
  * Grid lines are drawn between
  * each subsegment, in addition to each segment.
- * The preset default is \c 1, and it can not be below \c 1.
+ * The preset default is \c 1. The value cannot be below \c 1.
  *
  * \sa setSegmentCount()
  */
@@ -190,14 +193,14 @@ int QValue3DAxis::subSegmentCount() const
  *
  * \brief The label format to be used for the labels on this axis.
  *
- * How the format is interpreted
- * depends on the axis formatter and the locale in use. Using the default formatter and default
- * locale (\c{"C"}), the formatting uses QString::sprintf(). Supported specifiers are:
- * \c {d, i, o, x, X, f, F, e, E, g, G, c}. See QString::sprintf() for additional details.
- * For other locales, the default formatter uses reduced set of printf format specifiers:
- * \c {d, i, f, F, e, E, g, G}. In these cases, the only supported modifier is the precision
- * modifier for the floating point and exponential formats. The decimal point and other locale
- * dependent formatting is done according to the graph locale.
+ * The format string supports the following conversion specifiers, length
+ * modifiers, and flags provided by \c printf() in the standard C++ library:
+ * d, i, o, x, X, f, F, e, E, g, G, c.
+ *
+ * If QAbstract3DGraph::locale is anything else than \c{"C"}, the supported
+ * specifiers are limited to: d, e, E, f, g, G, and i. Also, only the precision
+ * modifier is supported. The rest of the formatting comes from the default
+ * QLocale of the application.
  *
  * Usage example:
  *
diff --git a/src/datavisualization/axis/qvalue3daxisformatter.cpp b/src/datavisualization/axis/qvalue3daxisformatter.cpp
index 01463894..4bc3e7e3 100644
--- a/src/datavisualization/axis/qvalue3daxisformatter.cpp
+++ b/src/datavisualization/axis/qvalue3daxisformatter.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,16 +35,17 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION
 /*!
  * \class QValue3DAxisFormatter
  * \inmodule QtDataVisualization
- * \brief QValue3DAxisFormatter is base class for value axis formatters.
+ * \brief The QValue3DAxisFormatter class is a base class for value axis
+ * formatters.
  * \since QtDataVisualization 1.1
  *
- * This class provides formatting rules for a linear QValue3DAxis. Subclass it if you
+ * This class provides formatting rules for a linear value 3D axis. Subclass it if you
  * want to implement custom value axes.
  *
  * The base class has no public API beyond constructors and destructors. It is meant to be only
  * used internally. However, subclasses may implement public properties as needed.
  *
- * \sa QLogValue3DAxisFormatter
+ * \sa QValue3DAxis, QLogValue3DAxisFormatter
  */
 
 /*!
@@ -53,11 +54,13 @@ QT_BEGIN_NAMESPACE_DATAVISUALIZATION
  * \since QtDataVisualization 1.1
  * \ingroup datavisualization_qml
  * \instantiates QValue3DAxisFormatter
- * \brief ValueAxis3DFormatter is base type for value axis formatters.
+ * \brief A base type for value axis formatters.
  *
- * This type provides formatting rules for a linear ValueAxis3D.
+ * This type provides formatting rules for a linear value 3D axis.
  * This type is the default type for ValueAxis3D and thus never needs to be explicitly created.
- * This type has not public functionality.
+ * This type has no public functionality.
+ *
+ * \sa ValueAxis3D
  */
 
 /*!
@@ -70,7 +73,7 @@ QValue3DAxisFormatter::QValue3DAxisFormatter(QValue3DAxisFormatterPrivate *d, QO
 }
 
 /*!
- * Constructs a new QValue3DAxisFormatter instance with an optional \a parent.
+ * Constructs a new value 3D axis formatter with the optional parent \a parent.
  */
 QValue3DAxisFormatter::QValue3DAxisFormatter(QObject *parent) :
     QObject(parent),
@@ -79,14 +82,14 @@ QValue3DAxisFormatter::QValue3DAxisFormatter(QObject *parent) :
 }
 
 /*!
- * Destroys QValue3DAxisFormatter.
+ * Deletes the value 3D axis formatter.
  */
 QValue3DAxisFormatter::~QValue3DAxisFormatter()
 {
 }
 
 /*!
- * Allow the parent axis to have negative values if \a allow is true.
+ * Allows the parent axis to have negative values if \a allow is \c true.
  */
 void QValue3DAxisFormatter::setAllowNegatives(bool allow)
 {
@@ -94,8 +97,8 @@ void QValue3DAxisFormatter::setAllowNegatives(bool allow)
 }
 
 /*!
- * \return \c true if negative values are valid values for parent axis.
- * The default implementation always returns true.
+ * Returns \c true if negative values are valid values for the parent axis.
+ * The default implementation always returns \c true.
  */
 bool QValue3DAxisFormatter::allowNegatives() const
 {
@@ -103,7 +106,7 @@ bool QValue3DAxisFormatter::allowNegatives() const
 }
 
 /*!
- * Allow the parent axis to have zero value if \a allow is true.
+ * Allows the parent axis to have a zero value if \a allow is \c true.
  */
 void QValue3DAxisFormatter::setAllowZero(bool allow)
 {
@@ -111,8 +114,8 @@ void QValue3DAxisFormatter::setAllowZero(bool allow)
 }
 
 /*!
- * \return \c true if zero is a valid value for parent axis.
- * The default implementation always returns true.
+ * Returns \c true if zero is a valid value for the parent axis.
+ * The default implementation always returns \c true.
  */
 bool QValue3DAxisFormatter::allowZero() const
 {
@@ -120,10 +123,11 @@ bool QValue3DAxisFormatter::allowZero() const
 }
 
 /*!
- * Creates a new empty instance of this formatter. Must be reimplemented in a subclass.
+ * Creates a new empty value 3D axis formatter. Must be reimplemented in a
+ * subclass.
  *
- * \return the new instance. The renderer uses this method to cache a copy of the
- * the formatter. The ownership of the new copy transfers to the caller.
+ * Returns the new formatter. The renderer uses this method to cache a copy of
+ * the formatter. The ownership of the new copy is transferred to the caller.
  */
 QValue3DAxisFormatter *QValue3DAxisFormatter::createNewInstance() const
 {
@@ -131,9 +135,9 @@ QValue3DAxisFormatter *QValue3DAxisFormatter::createNewInstance() const
 }
 
 /*!
- * This method resizes and populates the label and grid line position arrays and the label strings
- * array, as well as calculates any values needed for mapping between value and position.
- * It is allowed to access the parent axis from inside this function.
+ * Resizes and populates the label and grid line position arrays and the label
+ * strings array, as well as calculates any values needed to map a value to its
+ * position. The parent axis can be accessed from inside this function.
  *
  * This method must be reimplemented in a subclass if the default array contents are not suitable.
  *
@@ -148,13 +152,13 @@ void QValue3DAxisFormatter::recalculate()
 }
 
 /*!
- * This method is used to format a string using the specified value and the specified format.
+ * Returns the formatted label string using the specified \a value and
+ * \a format.
+ *
  * Reimplement this method in a subclass to resolve the formatted string for a given \a value
  * if the default formatting rules specified for QValue3DAxis::labelFormat property are not
  * sufficient.
  *
- * \return the formatted label string using a \a value and a \a format.
- *
  * \sa recalculate(), labelStrings(), QValue3DAxis::labelFormat
  */
 QString QValue3DAxisFormatter::stringForValue(qreal value, const QString &format) const
@@ -163,12 +167,13 @@ QString QValue3DAxisFormatter::stringForValue(qreal value, const QString &format
 }
 
 /*!
- * Reimplement this method if the position cannot be resolved by linear interpolation
- * between the parent axis minimum and maximum values.
+ * Returns the normalized position along the axis for the given \a value.
+ * The returned value should be between \c 0.0 (the minimum value) and
+ * \c 1.0 (the maximum value), inclusive, if the value is within the parent
+ * axis range.
  *
- * \return the normalized position along the axis for the given \a value.
- * The returned value should be between 0.0 (for minimum value) and 1.0 (for maximum value),
- * inclusive, if the value is within the parent axis range.
+ * Reimplement this method if the position cannot be resolved by linear
+ * interpolation between the parent axis minimum and maximum values.
  *
  * \sa recalculate(), valueAt()
  */
@@ -178,12 +183,13 @@ float QValue3DAxisFormatter::positionAt(float value) const
 }
 
 /*!
- * Reimplement this method if the value cannot be resolved by linear interpolation
- * between the parent axis minimum and maximum values.
+ * Returns the value at the normalized \a position along the axis.
+ * The \a position value should be between \c 0.0 (the minimum value) and
+ * \c 1.0 (the maximum value), inclusive, to obtain values within the parent
+ * axis range.
  *
- * \return the value at the normalized \a position along the axis.
- * The \a position value should be between 0.0 (for minimum value) and 1.0 (for maximum value),
- * inclusive to obtain values within the parent axis range.
+ * Reimplement this method if the value cannot be resolved by linear
+ * interpolation between the parent axis minimum and maximum values.
  *
  * \sa recalculate(), positionAt()
  */
@@ -193,12 +199,12 @@ float QValue3DAxisFormatter::valueAt(float position) const
 }
 
 /*!
- * Copies all necessary values for resolving positions, values, and strings with this formatter
- * from this formatter to the \a copy.
- * When reimplementing this method in a subclass, call the the superclass version at some point.
- * The renderer uses this method to cache a copy of the the formatter.
+ * Copies all the values necessary for resolving positions, values, and strings
+ * with this formatter to the \a copy of the formatter. When reimplementing
+ * this method in a subclass, call the superclass version at some point.
+ * The renderer uses this method to cache a copy of the formatter.
  *
- * \return the new copy. The ownership of the new copy transfers to the caller.
+ * Returns the new copy. The ownership of the new copy transfers to the caller.
  */
 void QValue3DAxisFormatter::populateCopy(QValue3DAxisFormatter &copy) const
 {
@@ -208,8 +214,8 @@ void QValue3DAxisFormatter::populateCopy(QValue3DAxisFormatter &copy) const
 /*!
  * Marks this formatter dirty, prompting the renderer to make a new copy of its cache on the next
  * renderer synchronization. This method should be called by a subclass whenever the formatter
- * is changed in a way that affects the resolved values. Specify \c true for \a labelsChange
- * parameter if the change was such that it requires regenerating the parent axis label strings.
+ * is changed in a way that affects the resolved values. Set \a labelsChange to
+ * \c true if the change requires regenerating the parent axis label strings.
  */
 void QValue3DAxisFormatter::markDirty(bool labelsChange)
 {
@@ -217,7 +223,7 @@ void QValue3DAxisFormatter::markDirty(bool labelsChange)
 }
 
 /*!
- * \return the parent axis. The parent axis must only be accessed in recalculate()
+ * Returns the parent axis. The parent axis must only be accessed in the recalculate()
  * method to maintain thread safety in environments using a threaded renderer.
  *
  * \sa recalculate()
@@ -228,10 +234,11 @@ QValue3DAxis *QValue3DAxisFormatter::axis() const
 }
 
 /*!
- * \return a reference to the array of normalized grid line positions.
+ * Returns a reference to the array of normalized grid line positions.
  * The default array size is equal to the segment count of the parent axis plus one, but
- * a subclassed implementation of recalculate method may resize the array differently.
- * The values should be between 0.0 (for minimum value) and 1.0 (for maximum value), inclusive.
+ * a subclassed implementation of the recalculate() method may resize the array differently.
+ * The values should be between \c 0.0 (the minimum value) and \c 1.0 (the
+ * maximum value), inclusive.
  *
  * \sa QValue3DAxis::segmentCount, recalculate()
  */
@@ -241,11 +248,12 @@ QVector<float> &QValue3DAxisFormatter::gridPositions() const
 }
 
 /*!
- * \return a reference to the array of normalized subgrid line positions.
- * The default array size is equal to segment count of the parent axis times sub-segment count
- * of the parent axis minus one, but a subclassed implementation of recalculate method may resize
- * the array differently.
- * The values should be between 0.0 (for minimum value) and 1.0 (for maximum value), inclusive.
+ * Returns a reference to the array of normalized subgrid line positions.
+ * The default array size is equal to the segment count of the parent axis times
+ * the sub-segment count of the parent axis minus one, but a subclassed
+ * implementation of the recalculate() method may resize the array differently.
+ * The values should be between \c 0.0 (the minimum value) and \c 1.0 (the
+ * maximum value), inclusive.
  *
  * \sa QValue3DAxis::segmentCount, QValue3DAxis::subSegmentCount, recalculate()
  */
@@ -255,11 +263,12 @@ QVector<float> &QValue3DAxisFormatter::subGridPositions() const
 }
 
 /*!
- * \return a reference to the array of normalized label positions.
+ * Returns a reference to the array of normalized label positions.
  * The default array size is equal to the segment count of the parent axis plus one, but
- * a subclassed implementation of recalculate method may resize the array differently.
- * The values should be between 0.0 (for minimum value) and 1.0 (for maximum value), inclusive.
- * The default behavior is that the label at the index zero corresponds to the minimum value
+ * a subclassed implementation of the recalculate() method may resize the array
+ * differently. The values should be between \c 0.0 (the minimum value) and
+ * \c 1.0 (the maximum value), inclusive.
+ * By default, the label at the index zero corresponds to the minimum value
  * of the axis.
  *
  * \sa QValue3DAxis::segmentCount, QAbstract3DAxis::labels, recalculate()
@@ -270,9 +279,9 @@ QVector<float> &QValue3DAxisFormatter::labelPositions() const
 }
 
 /*!
- * \return a reference to the string list containing formatter label strings.
- * The array size must be equal to the size of the label positions array and
- * the indexes correspond to that array as well.
+ * Returns a reference to the string list containing formatter label strings.
+ * The array size must be equal to the size of the label positions array, which
+ * the indexes also correspond to.
  *
  * \sa labelPositions()
  */
@@ -296,7 +305,7 @@ void QValue3DAxisFormatter::setLocale(const QLocale &locale)
     markDirty(true);
 }
 /*!
- * \return the current locale this formatter is using.
+ * Returns the current locale this formatter is using.
  */
 QLocale QValue3DAxisFormatter::locale() const
 {