From 730683467deed28e6bd28d45d39bdf38cd57f29b Mon Sep 17 00:00:00 2001 From: Leena Miettinen Date: Fri, 24 Mar 2017 09:51:14 +0100 Subject: Doc: Edit the axes documentation for grammar and style MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Change-Id: I2109585660af7cfcae2cfd779ebfc67d341a09f5 Reviewed-by: Tomi Korpipää --- src/datavisualization/axis/qabstract3daxis.cpp | 49 ++++---- src/datavisualization/axis/qcategory3daxis.cpp | 10 +- .../axis/qlogvalue3daxisformatter.cpp | 49 ++++---- src/datavisualization/axis/qvalue3daxis.cpp | 59 +++++----- .../axis/qvalue3daxisformatter.cpp | 125 +++++++++++---------- 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 ©) const { @@ -208,8 +214,8 @@ void QValue3DAxisFormatter::populateCopy(QValue3DAxisFormatter ©) 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 &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 &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 &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 { -- cgit v1.2.3