Doc: Edit box-and-whisker item and box plot series class and enum docs

Change-Id: I583d3892cfaff83fb4a5c4aadd16401799b9cd2e
Reviewed-by: Miikka Heikkinen <miikka.heikkinen@qt.io>

3 files changed, 226 insertions, 172 deletions

diff --git a/src/charts/boxplotchart/qboxplotseries.cpp b/src/charts/boxplotchart/qboxplotseries.cpp
index 26184735..221b940d 100644
--- a/src/charts/boxplotchart/qboxplotseries.cpp
+++ b/src/charts/boxplotchart/qboxplotseries.cpp
@@ -46,16 +46,14 @@ QT_CHARTS_BEGIN_NAMESPACE
 /*!
     \class QBoxPlotSeries
     \inmodule Qt Charts
-    \brief Series for creating box-and-whiskers chart.
+    \brief The QBoxPlotSeries class presents data in box-and-whiskers charts.
 
-    QBoxPlotSeries represents a series of data shown as box-and-whisker bars. The purpose of this
-    class is to act as a container for single box-and-whisker items. Each item is drawn to own slot.
-    If chart includes multiple instances of QBoxPlotSeries then box-and-whiskers items with the same
-    index are drawn to same slot.
+    A box plot series acts as a container for box-and-whiskers items. Items from multiple series
+    are grouped into categories according to their index value.
 
-    \note The slot, each item in QBoxPlotSeries is drawn, represents a category in QBarCategoryAxis.
-    The category labels have to be unique. If same category label is defined for several
-    box-and-whisker items only the first one is drawn.
+    The QBarCategoryAxis class is used to add the categories to the chart's axis. Category labels
+    have to be unique. If the same category label is defined for several box-and-whiskers items,
+    only the first one is drawn.
 
     See the \l {Box and Whiskers Example} {box-and-whiskers chart example} to learn how to create a
     box-and-whiskers chart.
@@ -65,91 +63,94 @@ QT_CHARTS_BEGIN_NAMESPACE
 */
 /*!
     \fn QBoxPlotSeries::boxsetsAdded(QList<QBoxSet *> sets)
-    \brief Signal is emitted when a new \a sets of box-and-whiskers data is added to the series.
+    This signal is emitted when the list of box-and-whiskers items specified by \a sets
+    is added to the series.
 */
 /*!
     \fn QBoxPlotSeries::boxsetsRemoved(QList<QBoxSet *> sets)
-    \brief Signal is emitted when \a sets of box-and-whiskers data is removed from the series.
+    This signal is emitted when the list of box-and-whiskers items specified by \a sets
+    is removed from the series.
 */
 /*!
     \fn QBoxPlotSeries::clicked(QBoxSet *boxset)
-    \brief Signal is emitted when the user clicks the \a boxset on the chart.
+    This signal is emitted when the user clicks the box-and-whiskers item specified by
+    \a boxset in the chart.
 */
 /*!
     \fn QBoxPlotSeries::pressed(QBoxSet *boxset)
-    \brief Signal is emitted when the user presses the \a boxset on the chart.
+    This signal is emitted when the user clicks the box-and-whiskers item specified by
+    \a boxset in the chart and holds down the mouse button.
 */
 /*!
     \fn QBoxPlotSeries::released(QBoxSet *boxset)
-    \brief Signal is emitted when the user releases the \a boxset on the chart.
+    This signal is emitted when the user releases the mouse press on the box-and-whiskers
+    item specified by \a boxset in the chart.
 */
 /*!
     \fn QBoxPlotSeries::doubleClicked(QBoxSet *boxset)
-    \brief Signal is emitted when the user doubleclicks the \a boxset on the chart.
+    This signal is emitted when the user double-clicks the box-and-whiskers item specified by
+    \a boxset in the chart.
 */
 /*!
     \fn QBoxPlotSeries::hovered(bool status, QBoxSet *boxset)
-    \brief Signal is emitted when there is change in hover \a status over \a boxset.
+    This signal is emitted when a mouse is hovered over the box-and-whiskers item specified by
+    \a boxset in the chart. When the mouse moves over the item, \a status turns \c true, and
+    when the mouse moves away again, it turns \c false.
 */
 /*!
     \fn QBoxPlotSeries::countChanged()
-    \brief Signal is emitted when there is change in count of box-and-whiskers items in the series.
+    This signal is emitted when the number of box-and-whiskers items in the series changes.
 */
 /*!
     \property QBoxPlotSeries::boxOutlineVisible
-    \brief This property configures the visibility of the middle box outline.
+    \brief The visibility of the box outline.
 */
 /*!
     \property QBoxPlotSeries::boxWidth
-    \brief This property configures the width of the box-and-whiskers item. The value signifies the relative
-    width of the box-and-whiskers item inside its own slot. The value can between 0.0 and 1.0. Negative values
-    are clamped to 0.0 and values over 1.0 are clamped to 1.0.
+    \brief The width of the box-and-whiskers item. The value indicates the relative
+    width of the item within its category. The value can be between 0.0 and 1.0. Negative values
+    are replaced with 0.0 and values greater than 1.0 are replaced with 1.0.
 */
 /*!
     \property QBoxPlotSeries::pen
-    \brief This property configures the pen of the box-and-whiskers items.
+    \brief The pen used to draw the lines of the box-and-whiskers items.
 */
 /*!
     \property QBoxPlotSeries::brush
-    \brief This property configures the brush of the box-and-whiskers items.
+    \brief The brush used to fill the boxes of the box-and-whiskers items.
 */
 /*!
     \property QBoxPlotSeries::count
-    \brief The count of sets in series.
-*/
-
-/*!
-    \qmlproperty QString BoxPlotSeries::brushFilename
-    The name of the file used as a brush for the series.
+    \brief The number of box-and-whiskers items in a box plot series.
 */
 
 /*!
     \fn void QBoxPlotSeries::boxOutlineVisibilityChanged()
-    Signal is emitted when the middle box outline visibility is changed.
+    This signal is emitted when the box outline visibility changes.
 */
+
 /*!
     \fn void QBoxPlotSeries::boxWidthChanged()
-    Signal is emitted when the width of the box-and-whiskers item is changed.
+    This signal is emitted when the width of the box-and-whiskers item changes.
 */
 /*!
     \fn void QBoxPlotSeries::penChanged()
-    This signal is emitted when the pen of the box-and-whiskers has changed.
-    \sa brush
+    This signal is emitted when the pen used to draw the lines of the box-and-whiskers
+    items changes.
 */
 /*!
     \fn void QBoxPlotSeries::brushChanged()
-    This signal is emitted when the brush of the box-and-whiskers has changed.
-    \sa brush
+    This signal is emitted when the brush used to fill the boxes of the box-and-whiskers
+    items changes.
 */
 /*!
     \fn virtual SeriesType QBoxPlotSeries::type() const
-    \brief Returns type of series.
+    Returns the type of the series.
     \sa QAbstractSeries, SeriesType
 */
 
 /*!
-    Constructs empty QBoxPlotSeries.
-    QBoxPlotSeries is QObject which is a child of a \a parent.
+    Constructs an empty box plot series that is a QObject and a child of \a parent.
 */
 QBoxPlotSeries::QBoxPlotSeries(QObject *parent)
     : QAbstractSeries(*new QBoxPlotSeriesPrivate(this), parent)
@@ -157,7 +158,7 @@ QBoxPlotSeries::QBoxPlotSeries(QObject *parent)
 }
 
 /*!
-    Destructor. Removes series from chart.
+    Removes the series from the chart.
 */
 QBoxPlotSeries::~QBoxPlotSeries()
 {
@@ -167,8 +168,9 @@ QBoxPlotSeries::~QBoxPlotSeries()
 }
 
 /*!
-    Adds a single box and whiskers set to series. Takes ownership of the \a set. If the set is null or is already in series, it won't be appended.
-    Returns true, if appending succeeded.
+    Adds a single box-and-whiskers item specified by \a set to the series and takes ownership of
+    it. If the item is null or it already belongs to the series, it will not be appended.
+    Returns \c true if appending succeeded.
 */
 bool QBoxPlotSeries::append(QBoxSet *set)
 {
@@ -186,7 +188,8 @@ bool QBoxPlotSeries::append(QBoxSet *set)
 }
 
 /*!
-    Removes boxset from the series. Deletes the \a set and returns true if successful.
+    Removes the box-and-whiskers item specified by \a set from the series and permanently
+    deletes it if the removal succeeds. Returns \c true if the item was removed.
 */
 bool QBoxPlotSeries::remove(QBoxSet *set)
 {
@@ -205,12 +208,14 @@ bool QBoxPlotSeries::remove(QBoxSet *set)
 }
 
 /*!
-    Takes a single \a set from the series. Does not delete the boxset object.
+    Takes the box-and-whiskers item specified by \a set from the series. Does not delete the
+    item.
+
+    \note The series remains the item's parent object. You must set the parent object to take
+    full ownership.
 
-    NOTE: The series remains as the boxset's parent object. You must set the
-    parent object to take full ownership.
+    Returns \c true if the take operation succeeds.
 
-    Returns true if take was successful.
 */
 bool QBoxPlotSeries::take(QBoxSet *set)
 {
@@ -227,10 +232,9 @@ bool QBoxPlotSeries::take(QBoxSet *set)
 }
 
 /*!
-    Adds a list of boxsets to series. Takes ownership of the \a sets.
-    Returns true, if all sets were appended successfully. If any of the sets is null or is already appended to series,
-    nothing is appended and function returns false. If any of the sets is in list more than once, nothing is appended
-    and function returns false.
+    Adds a list of box-and-whiskers items specified by \a sets to the series and takes ownership of
+    them. If the list is null or the items already belong to the series, it will not be appended.
+    Returns \c true if appending succeeded.
 */
 bool QBoxPlotSeries::append(QList<QBoxSet *> sets)
 {
@@ -244,9 +248,9 @@ bool QBoxPlotSeries::append(QList<QBoxSet *> sets)
 }
 
 /*!
-    Insert a box-and-whiskers set to the series at \a index postion. Takes ownership of the \a set. If the set is null or
-    is already in series, it won't be appended. Returns true, if inserting succeeded.
-
+    Inserts a box-and-whiskers item specified by \a set to a series at the position specified by
+    \a index and takes ownership of the item. If the item is null or already belongs to the series,
+    it will not be appended. Returns \c true if inserting succeeds.
 */
 bool QBoxPlotSeries::insert(int index, QBoxSet *set)
 {
@@ -262,7 +266,7 @@ bool QBoxPlotSeries::insert(int index, QBoxSet *set)
 }
 
 /*!
-    Removes all boxsets from the series. Deletes removed sets.
+    Removes all box-and-whiskers items from the series and permanently deletes them.
 */
 void QBoxPlotSeries::clear()
 {
@@ -278,7 +282,7 @@ void QBoxPlotSeries::clear()
 }
 
 /*!
-    Returns number of sets in series.
+    Returns the number of box-and-whiskers items in a box plot series.
 */
 int QBoxPlotSeries::count() const
 {
@@ -287,7 +291,7 @@ int QBoxPlotSeries::count() const
 }
 
 /*!
-    Returns a list of sets in series. Keeps ownership of sets.
+    Returns a list of box-and-whiskers items in a box plot series. Keeps the ownership of the items.
  */
 QList<QBoxSet *> QBoxPlotSeries::boxSets() const
 {
diff --git a/src/charts/boxplotchart/qboxset.cpp b/src/charts/boxplotchart/qboxset.cpp
index a92c8a19..59adc78d 100644
--- a/src/charts/boxplotchart/qboxset.cpp
+++ b/src/charts/boxplotchart/qboxset.cpp
@@ -36,93 +36,103 @@ QT_CHARTS_BEGIN_NAMESPACE
 /*!
     \class QBoxSet
     \inmodule Qt Charts
-    \brief Building block for box-and-whiskers chart.
+    \brief The QBoxSet class represents one item in a box-and-whiskers chart.
 
-    QBoxSet represents one box-and-whiskers item. It takes five values to create a graphical representation
-    of range and three medians. There are two ways to give the values. The first one is with constructor
-    or stream operator (<<). The values have to be given in the following order: lower extreme,
-    lower quartile, median, upper quartile and upper extreme. The Second method is to create an empty QBoxSet instance and
-    give the values using setValue method.
+    A box-and-whiskers item is a graphical representation of a range and three median values
+    that is constructed from five different values. There are two ways to specify the values.
+    The first one is by using a constructor or stream operator (<<). The values have to be
+    specified in the following order: lower extreme, lower quartile, median, upper quartile,
+    and upper extreme.
+
+    The second way is to create an empty QBoxSet instance and specify the values using the
+    setValue() method.
+
+    See the \l{Box and Whiskers Example}{box-and-whiskers chart example} to learn how to
+    create a box-and-whiskers chart.
 
     \sa QBoxPlotSeries
 */
 /*!
     \enum QBoxSet::ValuePositions
 
-    \value LowerExtreme
-    \value LowerQuartile
-    \value Median
-    \value UpperQuartile
-    \value UpperExtreme
+    This enum type defines the values of a box-and-whiskers item:
+
+    \value LowerExtreme The smallest value of the box-and-whiskers item.
+    \value LowerQuartile The median value of the lower half of the box-and-whiskers item.
+    \value Median The median value of the box-and-whiskers item.
+    \value UpperQuartile The median value of the upper half of the box-and-whiskers item.
+    \value UpperExtreme The largest value of the box-and-whiskers item.
 */
 /*!
     \property QBoxSet::pen
-    \brief Defines the pen used by the box-and-whiskers set.
+    \brief The pen used to draw the lines of the box-and-whiskers item.
 */
 /*!
     \property QBoxSet::brush
-    \brief Defines the brush used by the box-and-whiskers set.
+    \brief The brush used fill the box of the box-and-whiskers item.
 */
 
 /*!
     \qmlproperty QString BoxSet::brushFilename
-    The name of the file used as a brush for the box-and-whiskers set.
+    The name of the file used as a brush for the box-and-whiskers item.
 */
 
 /*!
     \fn void QBoxSet::clicked()
-    The signal is emitted if the user clicks with a mouse on top of box-and-whisker item.
+    This signal is emitted when the user clicks a box-and-whiskers item in the chart.
 */
 
 /*!
     \fn void QBoxSet::pressed()
-    The signal is emitted if the user presses with a mouse on top of box-and-whisker item.
+    This signal is emitted when the user clicks a box-and-whiskers item in the chart
+    and holds down the mouse button.
 */
 
 /*!
     \fn void QBoxSet::released()
-    The signal is emitted if the user releases with a mouse on top of box-and-whisker item.
+    This signal is emitted when the user releases the mouse press on a box-and-whiskers item.
 */
 
 /*!
     \fn void QBoxSet::doubleClicked()
-    The signal is emitted if the user doubleclicks with a mouse on top of box-and-whisker item.
+    This signal is emitted when the user double-clicks a box-and-whiskers item.
 */
 
 /*!
     \fn void QBoxSet::hovered(bool status)
 
-    The signal is emitted if mouse is hovered on top of box-and-whisker item.
-    Parameter \a status is true, if mouse entered on top of item, false if mouse left from top of item.
+    This signal is emitted when a mouse is hovered over a box-and-whiskers item in a chart.
+    When the mouse moves over the item, \a status turns \c true, and when the mouse moves
+    away again, it turns \c false.
 */
 /*!
     \fn void QBoxSet::penChanged()
-    This signal is emitted when the pen of the box-and-whisker item has changed.
+    This signal is emitted when the pen of the box-and-whiskers item changes.
     \sa pen
 */
 /*!
     \fn void QBoxSet::brushChanged()
-    This signal is emitted when the brush of the box-and-whisker item has changed.
+    This signal is emitted when the brush of the box-and-whiskers item changes.
     \sa brush
 */
 /*!
     \fn void QBoxSet::valuesChanged()
-    This signal is emitted when multiple values have been changed on the box-and-whisker item.
+    This signal is emitted when multiple values of the box-and-whiskers item change.
     \sa append()
 */
 /*!
     \fn void QBoxSet::valueChanged(int index)
-    This signal is emitted values the value in the box-and-whisker item has been modified.
-    Parameter \a index indicates the position of the modified value.
+    This signal is emitted when the value of the box-and-whiskers item specified by
+    \a index is modified.
     \sa at()
 */
 /*!
     \fn void QBoxSet::cleared()
-    This signal is emitted when all the values on the set are cleared to 0.
+    This signal is emitted when all the values of the box-and-whiskers item are set to 0.
 */
 
 /*!
-    Constructs QBoxSet with optional \a label and parent of \a parent
+    Constructs a box-and-whiskers item with the optional label \a label and parent \a parent.
 */
 QBoxSet::QBoxSet(const QString label, QObject *parent)
     : QObject(parent),
@@ -131,8 +141,9 @@ QBoxSet::QBoxSet(const QString label, QObject *parent)
 }
 
 /*!
-    Constructs QBoxSet with given ordered values. \a le for lower extreme, \a lq for lower quartile, \a m for median,
-    \a uq for upper quartile and \a ue for upper quartile. \a label and \a parent are optional.
+    Constructs a box-and-whiskers item with the following ordered values: \a le specifies the
+    lower extreme, \a lq the lower quartile, \a m the median, \a uq the upper quartile, and
+    \a ue the upper quartile. Optionally, the \a label and \a parent can be specified.
  */
 QBoxSet::QBoxSet(const qreal le, const qreal lq, const qreal m, const qreal uq, const qreal ue, const QString label, QObject *parent)
     : QObject(parent),
@@ -146,14 +157,14 @@ QBoxSet::QBoxSet(const qreal le, const qreal lq, const qreal m, const qreal uq,
 }
 
 /*!
-    Destroys the boxset
+    Destroys the a box-and-whiskers item.
 */
 QBoxSet::~QBoxSet()
 {
 }
 
 /*!
-    Appends new value \a value to the end of set.
+    Appends the new value specified by \a value to the end of the box-and-whiskers item.
 */
 void QBoxSet::append(const qreal value)
 {
@@ -162,8 +173,7 @@ void QBoxSet::append(const qreal value)
 }
 
 /*!
-    Appends a list of reals to set. Works like append with single real value. The \a values in list
-    are appended to end of boxset.
+    Appends a list of real values specified by \a values to the end of the box-and-whiskers item.
     \sa append()
 */
 void QBoxSet::append(const QList<qreal> &values)
@@ -173,7 +183,7 @@ void QBoxSet::append(const QList<qreal> &values)
 }
 
 /*!
-    Sets new \a label for the category of the set.
+    Sets the label specified by \a label for the category of the box-and-whiskers item.
 */
 void QBoxSet::setLabel(const QString label)
 {
@@ -181,7 +191,7 @@ void QBoxSet::setLabel(const QString label)
 }
 
 /*!
-    Returns the label of the the category of the set.
+    Returns the label of the category of the box-and-whiskers item.
 */
 QString QBoxSet::label() const
 {
@@ -189,7 +199,8 @@ QString QBoxSet::label() const
 }
 
 /*!
-    Convenience operator. Same as append, with real \a value.
+    A convenience operator for appending the real value specified by \a value to the end
+    of the box-and-whiskers item.
     \sa append()
 */
 QBoxSet &QBoxSet::operator << (const qreal &value)
@@ -199,7 +210,8 @@ QBoxSet &QBoxSet::operator << (const qreal &value)
 }
 
 /*!
-    Sets a new \a value on the \a index position. For \a index ValuePositions can be used.
+    Sets the value specified by \a value in the position specified by \a index.
+    The index can be specified by using the ValuePositions enumeration values.
 */
 void QBoxSet::setValue(const int index, const qreal value)
 {
@@ -208,7 +220,7 @@ void QBoxSet::setValue(const int index, const qreal value)
 }
 
 /*!
-    Sets all values on the set to 0.
+    Sets all the values of the box-and-whiskers item to 0.
  */
 void QBoxSet::clear()
 {
@@ -217,8 +229,9 @@ void QBoxSet::clear()
 }
 
 /*!
-    Returns value of set indexed by \a index. For \a index ValuePositions can be used.
-    If the index is out of bounds 0.0 is returned.
+    Returns the value of the box-and-whiskers item specified by \a index.
+    The index can be specified by using ValuePositions enumeration values.
+    If the index is out of bounds, 0.0 is returned.
 */
 qreal QBoxSet::at(const int index) const
 {
@@ -228,8 +241,9 @@ qreal QBoxSet::at(const int index) const
 }
 
 /*!
-    Returns value of set indexed by \a index. For \a index ValuePositions can be used.
-    If the index is out of bounds 0.0 is returned.
+    Returns the value of the box-and-whiskers item specified by \a index.
+    The index can be specified by using ValuePositions enumeration values.
+    If the index is out of bounds, 0.0 is returned.
 */
 qreal QBoxSet::operator [](const int index) const
 {
@@ -237,7 +251,7 @@ qreal QBoxSet::operator [](const int index) const
 }
 
 /*!
-    Returns count of values appended to the set.
+    Returns the number of values appended to the box-and-whiskers item.
 */
 int QBoxSet::count() const
 {
@@ -245,7 +259,7 @@ int QBoxSet::count() const
 }
 
 /*!
-    Sets pen for set. Boxes of this set are drawn using \a pen
+    Sets the pen used to draw the box-and-whiskers item to \a pen.
 */
 void QBoxSet::setPen(const QPen &pen)
 {
@@ -257,7 +271,7 @@ void QBoxSet::setPen(const QPen &pen)
 }
 
 /*!
-    Returns pen of the set.
+    Returns the pen used to draw the box-and-whiskers item.
 */
 QPen QBoxSet::pen() const
 {
@@ -265,7 +279,7 @@ QPen QBoxSet::pen() const
 }
 
 /*!
-    Sets brush for the set. Boxes of this set are drawn using \a brush
+    Sets the brush used to fill the box-and-whiskers item to \a brush.
 */
 void QBoxSet::setBrush(const QBrush &brush)
 {
@@ -277,7 +291,7 @@ void QBoxSet::setBrush(const QBrush &brush)
 }
 
 /*!
-    Returns brush of the set.
+    Returns the brush used to fill the box-and-whiskers item.
 */
 QBrush QBoxSet::brush() const
 {
diff --git a/src/chartsqml2/declarativeboxplotseries.cpp b/src/chartsqml2/declarativeboxplotseries.cpp
index 1ae3163e..abe53f4f 100644
--- a/src/chartsqml2/declarativeboxplotseries.cpp
+++ b/src/chartsqml2/declarativeboxplotseries.cpp
@@ -39,84 +39,103 @@ QT_CHARTS_BEGIN_NAMESPACE
     \instantiates QBoxSet
     \inqmlmodule QtCharts
 
-    \brief Building block for box-and-whiskers chart.
+    \brief Represents one item in a box-and-whiskers chart.
+
+    A box-and-whiskers item is a graphical representation of a range and three median values
+    that is constructed from five different values. There are two ways to specify the values.
+    The first one is by using a constructor or the append() method. The values have to be
+    specified in the following order: lower extreme, lower quartile, median, upper quartile,
+    and upper extreme.
+
+    The second way is to create an empty BoxSet instance and specify the values using the
+    setValue() method.
 
-    BoxSet represents one box-and-whiskers item. It takes five values to create a graphical
-    representation of range and three medians. There are two ways to give the values. The first one
-    is with constructor or with append method. In these the values have to be given in the following
-    order: lower extreme, lower quartile, median, upper quartile and upper extreme. The second
-    method is to create an empty QBoxSet instance and give the values using value specific methods.
     \sa BoxPlotSeries
 */
+
+/*!
+    \qmlproperty enumeration BoxSet::ValuePositions
+
+    This enum type defines the values of a box-and-whiskers item:
+
+    \value BoxSet.LowerExtreme The smallest value of the box-and-whiskers item.
+    \value BoxSet.LowerQuartile The median value of the lower half of the box-and-whiskers item.
+    \value BoxSet.Median The median value of the box-and-whiskers item.
+    \value BoxSet.UpperQuartile The median value of the upper half of the box-and-whiskers item.
+    \value BoxSet.UpperExtreme The largest value of the box-and-whiskers item.
+*/
+
 /*!
     \qmlproperty string BoxSet::values
-    The values on the box-and-whiskers set.
+    The values of the box-and-whiskers item.
 */
 /*!
     \qmlproperty string BoxSet::label
-    Defines the label of the category of the box-and-whiskers set.
+    The label of the category of the box-and-whiskers item.
 */
 /*!
     \qmlproperty int BoxSet::count
-    The count of values on the box-and-whiskers set
+    The number of values of the box-and-whiskers item.
 */
 /*!
     \qmlmethod void BoxSet::at(int index)
-    Returns the value at \a index position.
+    Returns the value in the position specified by \a index.
 */
 /*!
     \qmlmethod void BoxSet::append(qreal value)
-    Appends new value \a value to the end of set.
+    Appends the new value specified by \a value to the end of the box-and-whiskers item.
 */
 /*!
     \qmlmethod void BoxSet::clear()
-    Sets all values on the set to 0.
+    Sets all the values of the box-and-whiskers item to 0.
 */
 /*!
     \qmlmethod void BoxSet::setValue(int index, qreal value)
-    Sets a new \a value on the \a index position.
+    Sets the value specified by \a value in the position specified by \a index.
 */
 /*!
     \qmlsignal BoxSet::onClicked()
-    This signal is emitted when the user clicks with a mouse on top of box-and-whiskers item.
+    This signal is emitted when the user clicks a box-and-whiskers item in the chart.
 */
 /*!
     \qmlsignal BoxSet::onPressed()
-    This signal is emitted when the user presses with a mouse on top of box-and-whiskers item.
+    This signal is emitted when the user clicks a box-and-whiskers item in the chart
+    and holds down the mouse button.
 */
 /*!
     \qmlsignal BoxSet::onReleased()
-    This signal is emitted when the user releases with a mouse on top of box-and-whiskers item.
+    This signal is emitted when the user releases the mouse press on a box-and-whiskers item.
 */
 /*!
     \qmlsignal BoxSet::onDoubleClicked()
-    This signal is emitted when the user doubleclicks with a mouse on top of box-and-whiskers item.
+    This signal is emitted when the user double-clicks a box-and-whiskers item.
 */
 /*!
     \qmlsignal BoxSet::onHovered(bool status)
-    The signal is emitted if mouse is hovered on top of box-and-whiskers item.
-    Parameter \a status is true, if mouse entered on top of the item, and false if mouse left from top of the item.
+    This signal is emitted when a mouse is hovered over a box-and-whiskers item in a chart.
+    When the mouse moves over the item, \a status turns \c true, and when the mouse moves
+    away again, it turns \c false.
 */
 /*!
     \qmlsignal BoxSet::onPenChanged()
-    This signal is emitted when the pen of the box-and-whiskers item has changed.
+    This signal is emitted when the pen used to draw the lines of the box-and-whiskers item changes.
 */
 /*!
     \qmlsignal BoxSet::onBrushChanged()
-    This signal is emitted when the brush of the box-and-whiskers item has changed.
+    This signal is emitted when the brush used to fill the box of the box-and-whiskers item changes.
 */
 /*!
     \qmlsignal BoxSet::onChangedValues()
-    This signal is emitted when multiple values have been changed on the box-and-whiskers item.
+    This signal is emitted when multiple values of the box-and-whiskers item change.
 */
 /*!
     \qmlsignal BoxSet::onChangedValue(int index)
-    This signal is emitted values the value in the box-and-whiskers item has been modified.
-    Parameter \a index indicates the position of the modified value.
+    This signal is emitted when the value of the box-and-whiskers item specified by \a index
+    changes.
 */
 /*!
     \qmlsignal BoxSet::onCleared()
-    This signal is emitted when all the values on the set are cleared to 0.
+    This signal is emitted when all the values of the box-and-whiskers item are set to 0.
 */
 
 /*!
@@ -126,18 +145,16 @@ QT_CHARTS_BEGIN_NAMESPACE
 
     \inherits AbstractSeries
 
-    \brief Series for creating box-and-whiskers chart.
+    \brief Presents data in box-and-whiskers charts.
 
-    BoxPlotSeries represents a series of data shown as box-and-whiskers bars. The purpose of this
-    class is to act as a container for single box-and-whiskers items. Each item is drawn to own
-    slot. If chart includes multiple instances of BoxPlotSeries then box-and-whiskers items with the
-    same index are drawn to same slot.
+    A box plot series acts as a container for box-and-whiskers items. Items from multiple series
+    are grouped into categories according to their index value.
 
-    \note The slot, each item in BoxPlotSeries is drawn, represents a category in BarCategoryAxis.
-    The category labels have to be unique. If same category label is defined for several
-    box-and-whisker items only the first one is drawn.
+    The BarCategoryAxis class is used to add the categories to the chart's axis. Category labels
+    have to be unique. If the same category label is defined for several box-and-whiskers items,
+    only the first one is drawn.
 
-    The following QML shows how to create a simple box-and-whiskers chart:
+    The following QML code snippet shows how to create a simple box-and-whiskers chart:
     \code
     import QtQuick 2.0
     import QtCharts 2.0
@@ -171,31 +188,36 @@ QT_CHARTS_BEGIN_NAMESPACE
 
 /*!
     \qmlmethod BoxPlotSeries::append(string label, VariantList values)
-    Appends a new box-and-whiskers set with \a label and \a values to the series.
+    Appends a new box-and-whiskers item with the label specified by \a label and the values
+    specified by \a values to the series.
  */
 /*!
     \qmlmethod BoxPlotSeries::append(BoxSet box)
-    Appends the \a box to the series.
+    Appends the box-and-whiskers item specified by \a box to the series.
 */
 /*!
     \qmlmethod BoxPlotSeries::insert(int index, string label, VariantList values)
-    Inserts a new box-and-whiskers set with \a label and \a values at the \a index position.
+    Inserts a new box-and-whiskers item with the label specified by \a label and the values
+    specified by \a values to the series at the position specified by \a index.
 */
 /*!
     \qmlmethod BoxPlotSeries::remove(QBoxSet boxset)
-    Removes the \a boxset from the series.
+    Removes the box-and-whiskers item specified by \a boxset from the series.
 */
 /*!
     \qmlmethod BoxPlotSeries::clear()
-    Removes all boxsets from the series. Deletes removed sets.
+    Removes all box-and-whiskers items from the series and permanently deletes them.
 */
 /*!
     \qmlsignal BoxPlotSeries::onClicked(BoxSet boxset);
-    Signal is emitted when the user clicks the \a boxset on the chart.
+    This signal is emitted when the user clicks the box-and-whiskers item specified by
+    \a boxset in the chart.
 */
 /*!
     \qmlsignal BoxPlotSeries::onHovered(bool status, BoxSet boxset);
-    Signal is emitted when there is change in hover \a status over \a boxset.
+    This signal is emitted when a mouse is hovered over the box-and-whiskers item specified by
+    \a boxset in the chart. When the mouse moves over the item, \a status turns \c true, and
+    when the mouse moves away again, it turns \c false.
 */
 /*!
     \qmlsignal BoxPlotSeries::onPressed(BoxSet boxset)
@@ -203,101 +225,115 @@ QT_CHARTS_BEGIN_NAMESPACE
 */
 /*!
     \qmlsignal BoxPlotSeries::onReleased(BoxSet boxset)
-    This signal is emitted when the user releases the \a boxset on the chart.
+    This signal is emitted when the user releases the mouse press on the box-and-whiskers
+    item specified by \a boxset in the chart.
 */
 /*!
     \qmlsignal BoxPlotSeries::onDoubleClicked(BoxSet boxset)
-    This signal is emitted when the user doubleclicks the \a boxset on the chart.
+    This signal is emitted when the user double-clicks the box-and-whiskers item specified by
+    \a boxset in the chart.
 */
 /*!
     \qmlsignal BoxPlotSeries::onCountChanged();
-    Signal is emitted when there is change in count of box-and-whiskers items in the series.
+    This signal is emitted when the number of box-and-whiskers items in the series changes.
 */
 /*!
     \qmlsignal BoxPlotSeries::onBoxsetsAdded()
-    Signal is emitted when new box-and-whiskers sets are added to the series.
+    This signal is emitted when new box-and-whiskers items are added to the series.
  */
 /*!
     \qmlsignal BoxPlotSeries::onBoxsetsRemoved()
-    Signal is emitted when new box-and-whiskers sets are removed from the series.
+    This signal is emitted when box-and-whiskers items are removed from the series.
  */
 /*!
     \qmlproperty AbstractAxis BoxPlotSeries::axisX
-    The x axis used for the series. If you leave both axisX and axisXTop undefined, a BarCategoriesAxis is created for
-    the series.
+    The x-axis used for the series. If you leave both axisX and axisXTop undefined, a
+    BarCategoryAxis is created for the series.
     \sa axisXTop
 */
 /*!
     \qmlproperty AbstractAxis BoxPlotSeries::axisY
-    The y axis used for the series. If you leave both axisY and axisYRight undefined, a ValueAxis is created for
-    the series.
+    The y-axis used for the series. If you leave both axisY and axisYRight undefined, a
+    ValueAxis is created for the series.
     \sa axisYRight
 */
 /*!
     \qmlproperty AbstractAxis BoxPlotSeries::axisXTop
-    The x axis used for the series, drawn on top of the chart view. Note that you can only provide either axisX or
-    axisXTop, but not both.
+    The x-axis used for the series, drawn on top of the chart view.
+
+    \note You can only provide either axisX or axisXTop, but not both.
+    \sa axisX
+
     \sa axisX
 */
 /*!
     \qmlproperty AbstractAxis BoxPlotSeries::axisYRight
-    The y axis used for the series, drawn to the right on the chart view. Note that you can only provide either axisY
-    or axisYRight, but not both.
+    The y-axis used for the series, drawn to the right on the chart view.
+
+    \note You can only provide either axisY or axisYRight, but not both.
     \sa axisY
 */
 /*!
     \qmlproperty bool BoxPlotSeries::boxOutlineVisible
-    This property configures the visibility of the middle box outline.
+    The visibility of the box outline.
 */
 /*!
-    \qmlproperty qreal BoxPlotSeries::boxWidth
-    This property configures the width of the box-and-whiskers item. The value signifies the relative
-    width of the box-and-whiskers item inside its own slot. The value can between 0.0 and 1.0. Negative values
-    are clamped to 0.0 and values over 1.0 are clamped to 1.0.
+    \qmlproperty real BoxPlotSeries::boxWidth
+    \brief The width of the box-and-whiskers item. The value indicates the relative
+    width of the item within its category. The value can be between 0.0 and 1.0. Negative values
+    are replaced with 0.0 and values greater than 1.0 are replaced with 1.0.
 */
 /*!
     \qmlproperty Pen BoxPlotSeries::pen
-    This property configures the pen of the box-and-whiskers items.
+    The pen used to draw the lines of the box-and-whiskers items.
 */
 /*!
     \qmlproperty Brush BoxPlotSeries::brush
-    This property configures the brush of the box-and-whiskers items.
+    The brush used to fill the boxes of the box-and-whiskers items.
 */
+
+/*!
+    \qmlproperty string BoxPlotSeries::brushFilename
+    The name of the file used as a brush for the series.
+*/
+
 /*!
     \qmlproperty int BoxPlotSeries::count
-    The count of sets in series.
+    The number of box-and-whiskers items in a box plot series.
 */
 /*!
     \qmlsignal BoxPlotSeries::onBoxOutlineVisibilityChanged()
-    Signal is emitted when the middle box outline visibility is changed.
+    This signal is emitted when the box outline visibility changes.
  */
 /*!
     \qmlsignal BoxPlotSeries::onBoxWidthChanged()
-    Signal is emitted when the width of the box-and-whiskers item is changed.
+    This signal is emitted when the width of the box-and-whiskers item changes.
  */
 /*!
     \qmlsignal BoxPlotSeries::onPenChanged()
-    Signal is emitted when the pen for box-and-whiskers items has changed.
+    This signal is emitted when the pen used to draw the lines of the box-and-whiskers
+    items changes.
 */
 /*!
     \qmlsignal BoxPlotSeries::onBrushChanged()
-    Signal is emitted when the brush for box-and-whiskers items has changed.
+    This signal is emitted when the brush used to fill the boxes of the box-and-whiskers
+    items changes.
 */
 /*!
     \qmlsignal BoxPlotSeries::onAxisXChanged(AbstractAxis axis)
-    Signal is emitted when there is change in X axis.
+    This signal is emitted when the x-axis changes to \a axis.
 */
 /*!
     \qmlsignal BoxPlotSeries::onAxisYChanged(AbstractAxis axis)
-    Signal is emitted when there is change in Y axis.
+    This signal is emitted when the y-axis changes to \a axis.
 */
 /*!
     \qmlsignal BoxPlotSeries::onAxisXTopChanged(AbstractAxis axis)
-    Signal is emitted when there is change in top X axis.
+    This signal is emitted when the top x-axis changes to \a axis.
 */
 /*!
     \qmlsignal BoxPlotSeries::onAxisYRightChanged(AbstractAxis axis)
-    Signal is emitted when there is change in Y right axis.
+    This signal is emitted when the right y-axis changes to \a axis.
 */