From 832b68ef6fc68b91532163017713aa21739baa23 2012-02-24 13:55:48
From: Jani Honkonen <jani.honkonen@digia.com>
Date: 2012-02-24 13:55:48
Subject: [PATCH] More documentation for pie

---

diff --git a/src/piechart/qpieseries.cpp b/src/piechart/qpieseries.cpp
index 9a52326..3be2d29 100644
--- a/src/piechart/qpieseries.cpp
+++ b/src/piechart/qpieseries.cpp
@@ -7,42 +7,46 @@
 
 QTCOMMERCIALCHART_BEGIN_NAMESPACE
 
+
 /*!
-    \enum QPieSeries::PiePosition
+    \class QPieSeries::ChangeSet
+    \brief Defines the changes in the series.
 
-    This enum describes pie position within its bounding rectangle
+    Contains the changes that have occurred in the series. Lists of added, changed and removed slices.
 
-    \value PiePositionMaximized
-    \value PiePositionTopLeft
-    \value PiePositionTopRight
-    \value PiePositionBottomLeft
-    \value PiePositionBottomRight
+    \sa QPieSeries::changed()
 */
 
 /*!
-    \class QPieSeries
-    \brief QtCommercial charts pie series API.
-
+    \internal
 */
-
 void QPieSeries::ChangeSet::appendAdded(QPieSlice* slice)
 {
     if (!m_added.contains(slice))
         m_added << slice;
 }
 
+/*!
+    \internal
+*/
 void QPieSeries::ChangeSet::appendAdded(QList<QPieSlice*> slices)
 {
     foreach (QPieSlice* s, slices)
         appendAdded(s);
 }
 
+/*!
+    \internal
+*/
 void QPieSeries::ChangeSet::appendChanged(QPieSlice* slice)
 {
     if (!m_changed.contains(slice))
         m_changed << slice;
 }
 
+/*!
+    \internal
+*/
 void QPieSeries::ChangeSet::appendRemoved(QPieSlice* slice)
 {
     if (!m_removed.contains(slice))
@@ -88,6 +92,30 @@ bool QPieSeries::ChangeSet::isEmpty() const
 }
 
 /*!
+    \enum QPieSeries::PiePosition
+
+    This enum describes pie position within its bounding rectangle
+
+    \value PiePositionMaximized
+    \value PiePositionTopLeft
+    \value PiePositionTopRight
+    \value PiePositionBottomLeft
+    \value PiePositionBottomRight
+*/
+
+/*!
+    \class QPieSeries
+    \brief Pie series API for QtCommercial Charts
+
+    The pie series defines a pie chart which consists of pie slices which are QPieSlice objects.
+    The slices can have any values as the QPieSeries will calculate its relative value to the sum of all slices.
+    The actual slice size (span) is determined by that relative value.
+
+    By default the pie is defined as full but it can be a partial pie.
+    This can be done by setting a starting angle and angle span to the series.
+*/
+
+/*!
     Constructs a series object which is a child of \a parent.
 */
 QPieSeries::QPieSeries(QObject *parent) :
@@ -109,7 +137,7 @@ QPieSeries::~QPieSeries()
 }
 
 /*!
-    Returns the type of the series which is always QChartSeries::SeriesTypePie.
+    Returns QChartSeries::SeriesTypePie.
 */
 QChartSeries::QChartSeriesType QPieSeries::type() const
 {
@@ -188,6 +216,7 @@ QPieSlice* QPieSeries::add(qreal value, QString name)
 
 /*!
     Removes a single \a slice from the series and deletes the slice.
+
     Do not reference this pointer after this call.
 */
 void QPieSeries::remove(QPieSlice* slice)
@@ -292,7 +321,7 @@ QPieSeries::PiePosition QPieSeries::position() const
 /*!
     Sets the \a startAngle and \a angleSpan of this series.
 
-    \sa
+    Full pie is 360 degrees where 0 degrees is at 12 a'clock.
 */
 void QPieSeries::setSpan(qreal startAngle, qreal angleSpan)
 {
diff --git a/src/piechart/qpieslice.cpp b/src/piechart/qpieslice.cpp
index c0c17e9..edc0623 100644
--- a/src/piechart/qpieslice.cpp
+++ b/src/piechart/qpieslice.cpp
@@ -9,8 +9,13 @@ QTCOMMERCIALCHART_BEGIN_NAMESPACE
 
 /*!
     \class QPieSlice
-    \brief QtCommercial charts pie series API.
+    \brief Defines a slice a pie series.
 
+    Holds all the data of a single slice in a QPieSeries and provides the means
+    to modify slice data and customize the visual appearance of the slice.
+
+    It also provides the means to customize user interaction with the slice by
+    providing signals for clicking and hover events.
 */
 
 /*!
@@ -27,7 +32,9 @@ QTCOMMERCIALCHART_BEGIN_NAMESPACE
 
 /*!
     Constructs an empty slice with a \a parent.
+
     Note that QPieSeries takes ownership of the slice when it is set/added.
+
     \sa QPieSeries::set(), QPieSeries::add()
 */
 QPieSlice::QPieSlice(QObject *parent)
@@ -128,6 +135,7 @@ qreal QPieSlice::explodeDistance() const
 
 /*!
     Returns the percentage of this slice compared to all slices in the same series.
+
     Updated internally after the slice is added to the series.
 */
 qreal QPieSlice::percentage() const
@@ -137,6 +145,9 @@ qreal QPieSlice::percentage() const
 
 /*!
     Returns the starting angle of this slice in the series it belongs to.
+
+    Full pie is 360 degrees where 0 degrees is at 12 a'clock.
+
     Updated internally after the slice is added to the series.
 */
 qreal QPieSlice::angle() const
@@ -146,6 +157,9 @@ qreal QPieSlice::angle() const
 
 /*!
     Returns the angle span of this slice in the series it belongs to.
+
+    Full pie is 360 degrees where 0 degrees is at 12 a'clock.
+
     Updated internally after the slice is added to the series.
 */
 qreal QPieSlice::angleSpan() const