Merge branch 'master' of git@scm.dev.nokia.troll.no:qt/qt

5 files changed, 327 insertions, 191 deletions

diff --git a/src/gui/graphicsview/qgraphicsitem.cpp b/src/gui/graphicsview/qgraphicsitem.cpp
index 3884af9..eaf9896 100644
--- a/src/gui/graphicsview/qgraphicsitem.cpp
+++ b/src/gui/graphicsview/qgraphicsitem.cpp
@@ -135,38 +135,39 @@
 
     \section1 Transformation
 
-    QGraphicsItem supports affine transformations in addition to its base
-    position, pos(). To change the item's transformation, you can pass
-    a transformation matrix to setTransform()
-
-    Item transformations accumulate from parent to child, so if both a
-    parent and child item are rotated 90 degrees, the child's total
-    transformation will be 180 degrees.  Similarly, if the item's
-    parent is scaled to 2x its original size, its children will also
-    be twice as large. An item's transformation does not affect its
-    own local geometry; all geometry functions (e.g., contains(),
-    update(), and all the mapping functions) still operate in local
-    coordinates. For convenience, QGraphicsItem provides the functions
-    sceneTransform(), which returns the item's total transformation
+    QGraphicsItem supports projective transformations in addition to its base
+    position, pos(). There are several ways to change an item's transformation.
+    For simple transformations, you can call either of the convenience
+    functions setRotation() or setScale(), or you can pass any transformation
+    matrix to setTransform(). For advanced transformation control you also have
+    the option of setting several combined transformations by calling
+    setTransformations().
+
+    Item transformations accumulate from parent to child, so if both a parent
+    and child item are rotated 90 degrees, the child's total transformation
+    will be 180 degrees. Similarly, if the item's parent is scaled to 2x its
+    original size, its children will also be twice as large. An item's
+    transformation does not affect its own local geometry; all geometry
+    functions (e.g., contains(), update(), and all the mapping functions) still
+    operate in local coordinates. For convenience, QGraphicsItem provides the
+    functions sceneTransform(), which returns the item's total transformation
     matrix (including its position and all parents' positions and
-    transformations), and scenePos(), which returns its position in
-    scene coordinates. To reset an item's matrix, call
-    resetTransform().
+    transformations), and scenePos(), which returns its position in scene
+    coordinates. To reset an item's matrix, call resetTransform().
 
-    Another way to apply transformation to an item is to use the , or
-    set the different transformation properties (transformOrigin,
-    x/y/zRotation, x/yScale, horizontal/verticalShear).  Those
-    properties come in addition to the base transformation
+    Certain transformation operations produce a different outcome depending on
+    the order in which they are applied. For example, if you scale an
+    transform, and then rotate it, you may get a different result than if the
+    transform was rotated first. However, the order you set the transformation
+    properties on QGraphicsItem does not affect the resulting transformation;
+    QGraphicsItem always applies the properties in a fixed, defined order:
 
-    The order you set the transformation properties does not affect
-    the resulting transformation The resulting transformation is
-    always computed in the following order
-
-    \code
-    [Origin] [Base] [RotateX] [RotateY] [RotateZ] [Shear] [Scale] [-Origin]
-    \endcode
-
-    Where [Base] is the stransformation set by setTransform
+    \list
+    \o The item's base transform is applied (transform())
+    \o The item's transformations list is applied in order (transformations())
+    \o The item is rotated relative to its transform origin point (rotation(), transformOriginPoint())
+    \o The item is scaled relative to its transform origin point (scale(), transformOriginPoint())
+    \endlist
 
     \section1 Painting
 
@@ -2969,11 +2970,10 @@ QMatrix QGraphicsItem::matrix() const
 
     Returns this item's transformation matrix.
 
-    Either the one set by setTransform, or the resulting transformation from
-    all the transfmation properties
-
-    If no matrix or transformation property has been set, the
-    identity matrix is returned. 
+    The transformation matrix is combined with the item's rotation(), scale()
+    and transformations() into a combined transformations for the item.
+    
+    The default transformation matrix is an identity matrix.
 
     \sa setTransform(), sceneTransform()
 */
@@ -2987,13 +2987,13 @@ QTransform QGraphicsItem::transform() const
 /*!
     \since 4.6
 
-    Returns the rotation around the Z axis.
-
-    The default is 0
+    Returns the clockwise rotation, in degrees, around the Z axis. The default
+    value is 0 (i.e., the item is not rotated).
 
-    \warning The value doesn't take in account any rotation set with the setTransform() method.
+    The rotation is combined with the item's scale(), transform() and
+    transformations() to map the item's coordinate system to the parent item.
 
-    \sa setRotation(), {Transformations}
+    \sa setRotation(), transformOriginPoint(), {Transformations}
 */
 qreal QGraphicsItem::rotation() const
 {
@@ -3005,9 +3005,19 @@ qreal QGraphicsItem::rotation() const
 /*!
     \since 4.6
 
-    Sets the rotation around the Z axis to \a angle degrees.
+    Sets the clockwise rotation \a angle, in degrees, around the Z axis. The
+    default value is 0 (i.e., the item is not rotated). Assigning a negative
+    value will rotate the item counter-clockwise. Normally the rotation angle
+    is in the range (-360, 360), but it's also possible to assign values
+    outside of this range (e.g., a rotation of 370 degrees is the same as a
+    rotation of 10 degrees).
+
+    The item is rotated around its transform origin point, which by default
+    is (0, 0). You can select a different transformation origin by calling
+    setTransformOriginPoint().
 
-    \warning The value doesn't take in account any rotation set with the setTransform() method.
+    The rotation is combined with the item's scale(), transform() and
+    transformations() to map the item's coordinate system to the parent item.
 
     \sa rotation(), setTransformOriginPoint(), {Transformations}
 */
@@ -3027,13 +3037,13 @@ void QGraphicsItem::setRotation(qreal angle)
 /*!
     \since 4.6
 
-    Returns the scale factor of the item.
+    Returns the scale factor of the item. The default scale factor is 1.0
+    (i.e., the item is not scaled).
 
-    The default is 1
+    The scale is combined with the item's rotation(), transform() and
+    transformations() to map the item's coordinate system to the parent item.
 
-    \warning The value doesn't take in account any scaling set with the setTransform() method.
-
-    \sa setScale(), {Transformations}
+    \sa setScale(), rotation(), {Transformations}
 */
 qreal QGraphicsItem::scale() const
 {
@@ -3045,9 +3055,17 @@ qreal QGraphicsItem::scale() const
 /*!
     \since 4.6
 
-    Sets the scale factor of the item to \a factor.
+    Sets the scale \a factor of the item. The default scale factor is 1.0
+    (i.e., the item is not scaled). A scale factor of 0.0 will collapse the
+    item to a single point. If you provide a negative scale factor, the
+    item will be flipped and mirrored (i.e., rotated 180 degrees).
+
+    The item is scaled around its transform origin point, which by default
+    is (0, 0). You can select a different transformation origin by calling
+    setTransformOriginPoint().
 
-    \warning The value doesn't take in account any scaling set with the setTransform() method.
+    The scale is combined with the item's rotation(), transform() and
+    transformations() to map the item's coordinate system to the parent item.
 
     \sa scale(), setTransformOriginPoint(), {Transformations}
 */
@@ -3068,9 +3086,17 @@ void QGraphicsItem::setScale(qreal factor)
 /*!
     \since 4.6
 
-    returns list of graphics transformations on the item.
+    Returns a list of graphics transforms that currently apply to this item.
 
-    \sa scale(), setTransformOriginPoint(), {Transformations}
+    QGraphicsTransform is for applying and controlling a chain of individual
+    transformation operations on an item. It's particularily useful in
+    animations, where each transform operation needs to be interpolated
+    independently, or differently.
+
+    The transformations are combined with the item's rotation(), scale() and
+    transform() to map the item's coordinate system to the parent item.
+
+    \sa scale(), rotation(), transformOriginPoint(), {Transformations}
 */
 QList<QGraphicsTransform *> QGraphicsItem::transformations() const
 {
@@ -3082,7 +3108,20 @@ QList<QGraphicsTransform *> QGraphicsItem::transformations() const
 /*!
     \since 4.6
 
-    Sets a list of graphics transformations on the item to \a transformations.
+    Sets a list of graphics \a transformations (QGraphicsTransform) that
+    currently apply to this item.
+
+    If all you want is to rotate or scale an item, you should call setRotation()
+    or setScale() instead. If you want to set an arbitrary transformation on
+    an item, you can call setTransform().
+
+    QGraphicsTransform is for applying and controlling a chain of individual
+    transformation operations on an item. It's particularily useful in
+    animations, where each transform operation needs to be interpolated
+    independently, or differently.
+
+    The transformations are combined with the item's rotation(), scale() and
+    transform() to map the item's coordinate system to the parent item.
 
     \sa scale(), setTransformOriginPoint(), {Transformations}
 */
@@ -3098,7 +3137,9 @@ void QGraphicsItem::setTransformations(const QList<QGraphicsTransform *> &transf
     d_ptr->dirtySceneTransform = 1;
 }
 
-
+/*!
+    \internal
+*/
 void QGraphicsItemPrivate::appendGraphicsTransform(QGraphicsTransform *t)
 {
     if (!transformData)
@@ -3432,7 +3473,9 @@ void QGraphicsItem::setMatrix(const QMatrix &matrix, bool combine)
     to map an item coordiate to a scene coordinate, or mapFromScene() to map
     from scene coordinates to item coordinates.
 
-    \warning using this function doesnt affect the value of the transformation properties
+    The transformation matrix is combined with the item's rotation(), scale()
+    and transformations() into a combined transformation that maps the item's
+    coordinate system to its parent.
 
     \sa transform(), setRotation(), setScale(), setTransformOriginPoint(), {The Graphics View Coordinate System}, {Transformations}
 */
@@ -3491,7 +3534,8 @@ void QGraphicsItem::resetTransform()
 
 /*!
     \obsolete
-    Use setZRotation() instead
+
+    Use setRotation() instead
 
     Rotates the current item transformation \a angle degrees clockwise around
     its origin. To translate around an arbitrary point (x, y), you need to
@@ -3501,8 +3545,6 @@ void QGraphicsItem::resetTransform()
 
     \snippet doc/src/snippets/code/src_gui_graphicsview_qgraphicsitem.cpp 6
 
-    \warning using this functionhas no effect on the zRotation value
-
     \sa setTransform(), transform(), scale(), shear(), translate()
 */
 void QGraphicsItem::rotate(qreal angle)
@@ -3512,6 +3554,7 @@ void QGraphicsItem::rotate(qreal angle)
 
 /*!
     \obsolete
+
     Use setScale() instead
 
     Scales the current item transformation by (\a sx, \a sy) around its
@@ -3522,8 +3565,6 @@ void QGraphicsItem::rotate(qreal angle)
 
     \snippet doc/src/snippets/code/src_gui_graphicsview_qgraphicsitem.cpp 7
 
-    \warning using this function has no effect on the xScale or yScale value
-
     \sa setTransform(), transform()
 */
 void QGraphicsItem::scale(qreal sx, qreal sy)
@@ -3533,11 +3574,10 @@ void QGraphicsItem::scale(qreal sx, qreal sy)
 
 /*!
     \obsolete
-    Use setShear instead.
 
-    Shears the current item transformation by (\a sh, \a sv).
+    Use setTransform() instead.
 
-    \warning using this function has no effect on the horizontalShear or verticalShear value
+    Shears the current item transformation by (\a sh, \a sv).
 
     \sa setTransform(), transform()
 */
@@ -3548,6 +3588,7 @@ void QGraphicsItem::shear(qreal sh, qreal sv)
 
 /*!
     \obsolete
+
     Use setPos() or setTransformOriginPoint() instead.
 
     Translates the current item transformation by (\a dx, \a dy).
diff --git a/src/gui/graphicsview/qgraphicsitem_p.h b/src/gui/graphicsview/qgraphicsitem_p.h
index b8d98c1..5c3622b 100644
--- a/src/gui/graphicsview/qgraphicsitem_p.h
+++ b/src/gui/graphicsview/qgraphicsitem_p.h
@@ -468,7 +468,8 @@ public:
     QGraphicsItem *q_ptr;
 };
 
-struct QGraphicsItemPrivate::TransformData {
+struct QGraphicsItemPrivate::TransformData
+{
     QTransform transform;
     qreal scale;
     qreal rotation;
@@ -481,7 +482,7 @@ struct QGraphicsItemPrivate::TransformData {
         scale(1.0), rotation(0.0),
         xOrigin(0.0), yOrigin(0.0),
         onlyTransform(true)
-    {}
+    { }
 
     QTransform computedFullTransform(QTransform *postmultiplyTransform = 0) const
     {
diff --git a/src/gui/graphicsview/qgraphicsscenebsptreeindex.cpp b/src/gui/graphicsview/qgraphicsscenebsptreeindex.cpp
index 3cb33d1..07d23b7 100644
--- a/src/gui/graphicsview/qgraphicsscenebsptreeindex.cpp
+++ b/src/gui/graphicsview/qgraphicsscenebsptreeindex.cpp
@@ -525,7 +525,7 @@ QGraphicsSceneBspTreeIndex::~QGraphicsSceneBspTreeIndex()
 }
 
 /*!
-    \reimp
+    \internal
     Clear the all the BSP index.
 */
 void QGraphicsSceneBspTreeIndex::clear()
@@ -566,7 +566,7 @@ void QGraphicsSceneBspTreeIndex::removeItem(QGraphicsItem *item)
 }
 
 /*!
-    \reimp
+    \internal
     Update the BSP when the \a item 's bounding rect has changed.
 */
 void QGraphicsSceneBspTreeIndex::prepareBoundingRectChange(const QGraphicsItem *item)
@@ -682,7 +682,7 @@ void QGraphicsSceneBspTreeIndex::setBspTreeDepth(int depth)
 }
 
 /*!
-    \reimp
+    \internal
 
     This method react to the  \a rect change of the scene and
     reset the BSP tree index.
@@ -695,11 +695,10 @@ void QGraphicsSceneBspTreeIndex::updateSceneRect(const QRectF &rect)
 }
 
 /*!
-    \reimp
+    \internal
 
     This method react to the \a change of the \a item and use the \a value to
     update the BSP tree if necessary.
-
 */
 void QGraphicsSceneBspTreeIndex::itemChange(const QGraphicsItem *item, QGraphicsItem::GraphicsItemChange change, const QVariant &value)
 {
diff --git a/src/gui/graphicsview/qgraphicstransform.cpp b/src/gui/graphicsview/qgraphicstransform.cpp
index b55d78e..890aff7 100644
--- a/src/gui/graphicsview/qgraphicstransform.cpp
+++ b/src/gui/graphicsview/qgraphicstransform.cpp
@@ -39,6 +39,43 @@
 **
 ****************************************************************************/
 
+/*!
+    \class QGraphicsTransform
+    \brief The QGraphicsTransform class is an abstract base class for building
+    advanced transformations on QGraphicsItems.
+    \since 4.6
+
+    As an alternative to QGraphicsItem::transform, QGraphicsTransform lets you
+    create and control advanced transformations that can be configured
+    independently using specialized properties.
+
+    QGraphicsItem allows you to assign any number of QGraphicsTransform
+    instances to one QGraphicsItem. Each QGraphicsTransform is applied in
+    order, one at a time, to the QGraphicsItem it's assigned to.
+
+    QGraphicsTransform is particularily useful for animations. Whereas
+    QGraphicsItem::setTransform() lets you assign any transform directly to an
+    item, there is no direct way to interpolate between two different
+    transformations (e.g., when transitioning between two states, each for
+    which the item has a different arbitrary transform assigned). Using
+    QGraphicsTransform you can interpolate the property values of each
+    independent transformation. The resulting operation is then combined into a
+    single transform which is applied to QGraphicsItem.
+
+    If you want to create your own configurable transformation, you can create
+    a subclass of QGraphicsTransform (or any or the existing subclasses), and
+    reimplement the pure virtual applyTo() function, which takes a pointer to a
+    QTransform. Each operation you would like to apply should be exposed as
+    properties (e.g., customTransform->setVerticalShear(2.5)). Inside you
+    reimplementation of applyTo(), you can modify the provided transform
+    respectively.
+
+    QGraphicsTransform can be used together with QGraphicsItem::setTransform(),
+    QGraphicsItem::setRotation(), and QGraphicsItem::setScale().
+
+    \sa QGraphicsItem::transform(), QGraphicsScale, QGraphicsRotation, QGraphicsRotation3D
+*/
+
 #include "qgraphicstransform.h"
 #include "qgraphicsitem_p.h"
 #include "qgraphicstransform_p.h"
@@ -51,7 +88,6 @@
 
 QT_BEGIN_NAMESPACE
 
-
 void QGraphicsTransformPrivate::setItem(QGraphicsItem *i)
 {
     if (item == i)
@@ -77,15 +113,38 @@ void QGraphicsTransformPrivate::updateItem(QGraphicsItem *item)
     item->d_ptr->dirtySceneTransform = 1;
 }
 
-void QGraphicsTransform::update()
+/*!
+    Constructs a new QGraphicsTransform with the given \a parent.
+*/
+QGraphicsTransform::QGraphicsTransform(QObject *parent)
+    : QObject(*new QGraphicsTransformPrivate, parent)
+{
+}
+
+/*!
+    Destroys the graphics transform.
+*/
+QGraphicsTransform::~QGraphicsTransform()
 {
     Q_D(QGraphicsTransform);
-    if (d->item)
-        d->updateItem(d->item);
+    d->setItem(0);
+}
+
+/*!
+    \internal
+*/
+QGraphicsTransform::QGraphicsTransform(QGraphicsTransformPrivate &p, QObject *parent)
+    : QObject(p, parent)
+{
 }
 
 /*!
-  returns this object as a QTransform.
+    Applies this transformation to an identity transform, and returns the
+    resulting transform.
+
+    This is equivalent to passing an identity transform to applyTo().
+
+    \sa applyTo()
 */
 QTransform QGraphicsTransform::transform() const
 {
@@ -95,76 +154,65 @@ QTransform QGraphicsTransform::transform() const
 }
 
 /*!
-  \class QGraphicsTransform
-  \brief The QGraphicsTransform class is an abstract base class for tranformations on QGraphicsItems.
-  \since 4.6
-
-  The classes that inherit QGraphicsTransform express different types of transformations
-  that can be applied to graphics items.
+    \fn void QGraphicsTransform::applyTo(QTransform *transform) const
 
-  A list of these transformations can be applied to any graphics item. These
-  transformations are then easily modifyable and usable from e.g. within animations.
+    This pure virtual method has to be reimplemented in derived classes.
 
-  QGraphicsTransform is an abstract base class that is implemented by QGraphicsScale,
-  QGraphicsRotation and QGraphicsRotation3D. Subclasses have to implement the applyTo method.
+    It applies this transformation to \a transform.
 
-  \sa QGraphicsItem::transform(), QGraphicsScale, QGraphicsRotation, QGraphicsRotation3D
+    \sa QGraphicsItem::transform()
 */
 
 /*!
-  Constructs a new QGraphicsTransform with \a parent.
-*/
-QGraphicsTransform::QGraphicsTransform(QObject *parent) :
-    QObject(*new QGraphicsTransformPrivate, parent)
-{
-}
+    Notifies that this transform operation has changed its parameters in such a
+    way that applyTo() will return a different result than before.
 
-/*!
-  Destructs the graphics transform.
+    When implementing you own custom graphics transform, you must call this
+    function every time you change a parameter, to let QGraphicsItem know that
+    its transformation needs to be updated.
+
+    \sa applyTo()
 */
-QGraphicsTransform::~QGraphicsTransform()
+void QGraphicsTransform::update()
 {
     Q_D(QGraphicsTransform);
-    d->setItem(0);
+    if (d->item)
+        d->updateItem(d->item);
 }
 
 /*!
-  \internal
-*/
-QGraphicsTransform::QGraphicsTransform(QGraphicsTransformPrivate &p, QObject *parent)
-    : QObject(p, parent)
-{
-}
-
-/*! \fn void QGraphicsTransform::applyTo(QTransform *transform) const
+  \class QGraphicsScale
+  \brief The QGraphicsScale class provides a scale transformation.
+  \since 4.6
 
-  This pure virtual method has to be reimplemented in derived classes.
+  QGraphicsScene provides certain parameters to help control how the scale
+  should be applied.
 
-  It applies this transformation to \a transform.
-*/
+  The origin is the point that the item is scaled from (i.e., it stays fixed
+  relative to the parent as the rest of the item grows). By default the
+  origin is QPointF(0, 0).
 
+  The two parameters xScale and yScale describe the scale factors to apply in
+  horizontal and vertical direction. They can take on any value, including 0
+  (to collapse the item to a point) or negativate value. A negative xScale
+  value will mirror the item horizontally. A negative yScale value will flip
+  the item vertically.
 
-/*!
-  \class QGraphicsScale
-  \brief The QGraphicsScale class provides a way to scale a graphics item in 2 dimensions.
-  \since 4.6
-
-  QGraphicsScale contains an \a origin around which the scaling happens, and two
-  scale factors, xScale and yScale, the x and one for the y axis.
+  \sa QGraphicsTransform, QGraphicsItem::setScale(), QTransform::scale()
 */
 
 class QGraphicsScalePrivate : public QGraphicsTransformPrivate
 {
 public:
     QGraphicsScalePrivate()
-            : xScale(1), yScale(1) {}
+        : xScale(1), yScale(1) {}
     QPointF origin;
     qreal xScale;
     qreal yScale;
 };
 
 /*!
-  Constructs a new graphics scale object with \a parent.
+    Constructs an empty QGraphicsScale object with the given \a parent.
 */
 QGraphicsScale::QGraphicsScale(QObject *parent)
     : QGraphicsTransform(*new QGraphicsScalePrivate, parent)
@@ -172,24 +220,26 @@ QGraphicsScale::QGraphicsScale(QObject *parent)
 }
 
 /*!
-  Destroys the object
+    Destroys the graphics scale.
 */
 QGraphicsScale::~QGraphicsScale()
 {
 }
 
 /*!
-  \property QGraphicsScale::origin
-  The origin of the scale. All scaling will be done relative to this point.
+    \property QGraphicsScale::origin
+    \brief The QGraphicsScene class provides the origin of the scale.
+
+    All scaling will be done relative to this point (i.e., this point
+    will stay fixed, relative to the parent, when the item is scaled).
 
-  The \a origin is in other words the fixed point for the transformation.
+    \sa xScale, yScale
 */
 QPointF QGraphicsScale::origin() const
 {
     Q_D(const QGraphicsScale);
     return d->origin;
 }
-
 void QGraphicsScale::setOrigin(const QPointF &point)
 {
     Q_D(QGraphicsScale);
@@ -199,26 +249,21 @@ void QGraphicsScale::setOrigin(const QPointF &point)
 }
 
 /*!
-  \fn QGraphicsScale::originChanged()
-
-  This signal is emitted whenever the origin of the object
-  changes.
-*/
-
-/*!
-  \property QGraphicsScale::xScale
+    \property QGraphicsScale::xScale
+    \brief the horizontal scale factor.
 
-  The scale factor in x direction. The x direction is
-  in the graphics items logical coordinates.
+    The scale factor can be any real number; the default value is 1.0. If you
+    set the factor to 0.0, the item will be collapsed to a single point. If you
+    provide a negative value, the item will be mirrored horizontally around its
+    origin.
 
-  \sa yScale
+    \sa yScale, origin
 */
 qreal QGraphicsScale::xScale() const
 {
     Q_D(const QGraphicsScale);
     return d->xScale;
 }
-
 void QGraphicsScale::setXScale(qreal scale)
 {
     Q_D(QGraphicsScale);
@@ -230,19 +275,21 @@ void QGraphicsScale::setXScale(qreal scale)
 }
 
 /*!
-  \property QGraphicsScale::yScale
+    \property QGraphicsScale::yScale
+    \brief the vertical scale factor.
 
-  The scale factor in y direction. The y direction is
-  in the graphics items logical coordinates.
+    The scale factor can be any real number; the default value is 1.0. If you
+    set the factor to 0.0, the item will be collapsed to a single point. If you
+    provide a negative value, the item will be flipped vertically around its
+    origin.
 
-  \sa xScale
+    \sa xScale, origin
 */
 qreal QGraphicsScale::yScale() const
 {
     Q_D(const QGraphicsScale);
     return d->yScale;
 }
-
 void QGraphicsScale::setYScale(qreal scale)
 {
     Q_D(QGraphicsScale);
@@ -254,14 +301,7 @@ void QGraphicsScale::setYScale(qreal scale)
 }
 
 /*!
-  \fn QGraphicsScale::scaleChanged()
-
-  This signal is emitted whenever the xScale or yScale of the object
-  changes.
-*/
-
-/*!
-  \reimp
+    \reimp
 */
 void QGraphicsScale::applyTo(QTransform *transform) const
 {
@@ -272,12 +312,41 @@ void QGraphicsScale::applyTo(QTransform *transform) const
 }
 
 /*!
-  \class QGraphicsRotation
-  \brief The QGraphicsRotation class provides a way to rotate a graphics item in 2 dimensions.
-  \since 4.6
+    \fn QGraphicsScale::originChanged()
+
+    QGraphicsScale emits this signal when its origin changes.
+
+    \sa QGraphicsScale::origin
+*/
+
+/*!
+    \fn QGraphicsScale::scaleChanged()
+
+    This signal is emitted whenever the xScale or yScale of the object
+    changes.
 
-  QGraphicsRotation contains an \a origin around which the rotation happens, and one
-  angle in degrees describing the amount of the rotation.
+    \sa QGraphicsScale::xScale, QGraphicsScale::yScale
+*/
+
+/*!
+    \class QGraphicsRotation
+    \brief The QGraphicsRotation class provides a rotation transformation.
+    \since 4.6
+
+    QGraphicsRotation provides certain parameters to help control how the
+    rotation should be applied.
+
+    The origin is the point that the item is rotated around (i.e., it stays
+    fixed relative to the parent as the rest of the item is rotated). By
+    default the origin is QPointF(0, 0).
+
+    The angle property provides the number of degrees to rotate the item
+    clockwise around the origin. This value also be negative, indicating a
+    counter-clockwise rotation. For animation purposes it may also be useful to
+    provide rotation angles exceeding (-360, 360) degrees, for instance to
+    animate how an item rotates several times.
+
+    \sa QGraphicsTransform, QGraphicsItem::setRotation(), QTransform::rotate()
 */
 
 class QGraphicsRotationPrivate : public QGraphicsTransformPrivate
@@ -291,7 +360,7 @@ public:
 };
 
 /*!
-  Constructs a new graphics rotation with \a parent.
+    Constructs a new QGraphicsRotation with the given \a parent.
 */
 QGraphicsRotation::QGraphicsRotation(QObject *parent)
     : QGraphicsTransform(*new QGraphicsRotationPrivate, parent)
@@ -299,7 +368,7 @@ QGraphicsRotation::QGraphicsRotation(QObject *parent)
 }
 
 /*!
-  \internal
+    \internal
 */
 QGraphicsRotation::QGraphicsRotation(QGraphicsRotationPrivate &p, QObject *parent)
     : QGraphicsTransform(p, parent)
@@ -307,24 +376,26 @@ QGraphicsRotation::QGraphicsRotation(QGraphicsRotationPrivate &p, QObject *paren
 }
 
 /*!
-  Destructs the object
+    Destroys the graphics rotation.
 */
 QGraphicsRotation::~QGraphicsRotation()
 {
 }
 
 /*!
-  \property QGraphicsRotation::origin
-  The origin around which this object will rotate the graphics item.
+    \property QGraphicsRotation::origin
+    \brief the origin of the rotation.
 
-  The \a origin is in other words the fixed point for the transformation.
+    All rotations will be done relative to this point (i.e., this point
+    will stay fixed, relative to the parent, when the item is rotated).
+
+    \sa angle
 */
 QPointF QGraphicsRotation::origin() const
 {
     Q_D(const QGraphicsRotation);
     return d->origin;
 }
-
 void QGraphicsRotation::setOrigin(const QPointF &point)
 {
     Q_D(QGraphicsRotation);
@@ -334,22 +405,22 @@ void QGraphicsRotation::setOrigin(const QPointF &point)
 }
 
 /*!
-  \fn QGraphicsRotation::originChanged()
+    \property QGraphicsRotation::angle
+    \brief the angle for clockwise rotation, in degrees.
 
-  This signal is emitted whenever the origin of the object
-  changes.
-*/
+    The angle can be any real number; the default value is 0.0. A value of 180
+    will rotate 180 degrees, clockwise. If you provide a negative number, the
+    item will be rotated counter-clockwise. Normally the rotation angle will be
+    in the range (-360, 360), but you can also provide numbers outside of this
+    range (e.g., a angle of 370 degrees gives the same result as 10 degrees).
 
-/*!
-  \property QGraphicsRotation::angle
-  The angle, in degrees, of the rotation.
+    \sa origin
 */
 qreal QGraphicsRotation::angle() const
 {
     Q_D(const QGraphicsRotation);
     return d->angle;
 }
-
 void QGraphicsRotation::setAngle(qreal angle)
 {
     Q_D(QGraphicsRotation);
@@ -361,33 +432,50 @@ void QGraphicsRotation::setAngle(qreal angle)
 }
 
 /*!
-  \fn void QGraphicsRotation::angleChanged()
-
-  This signal is emitted whenever the angle of the object
-  changes.
-*/
-
-/*!
-  \reimp
+    \reimp
 */
 void QGraphicsRotation::applyTo(QTransform *t) const
 {
     Q_D(const QGraphicsRotation);
-    if(d->angle) {
+    if (d->angle) {
         t->translate(d->origin.x(), d->origin.y());
         t->rotate(d->angle);
         t->translate(-d->origin.x(), -d->origin.y());
     }
 }
 
+/*!
+    \fn QGraphicsRotation::originChanged()
+
+    This signal is emitted whenever the origin has changed.
+
+    \sa QGraphicsRotation::origin
+*/
 
 /*!
-  \class QGraphicsRotation3D
-  \brief The QGraphicsRotation3D class provides a way to rotate a graphics item in 3 dimensions.
-  \since 4.6
+  \fn void QGraphicsRotation::angleChanged()
 
-  In addition to the origin and angle of a simple QGraphicsRotation, QGraphicsRotation3D contains
-  also an axis that describes around which axis in space the rotation is supposed to happen.
+  This signal is emitted whenever the angle has changed.
+
+  \sa QGraphicsRotation::angle
+*/
+
+/*!
+    \class QGraphicsRotation3D
+    \brief The QGraphicsRotation3D class provides rotation in 3 dimensions.
+    \since 4.6
+
+    QGraphicsRotation3D extends QGraphicsRotation with the ability to rotate
+    around a given axis.
+
+    You can provide the desired axis by assigning a QVector3D to the axis
+    property. The angle property, which is provided by QGraphicsRotation, now
+    describes the number of degrees to rotate around this axis.
+
+    By default the axis is (0, 0, 1), giving QGraphicsRotation3D the same
+    default behavior as QGraphicsRotation (i.e., rotation around the Z axis).
+
+    \sa QGraphicsTransform, QGraphicsItem::setRotation(), QTransform::rotate()
 */
 
 class QGraphicsRotation3DPrivate : public QGraphicsRotationPrivate
@@ -399,7 +487,7 @@ public:
 };
 
 /*!
-  Constructs a new 3D rotation with \a parent.
+    Constructs a new QGraphicsRotation3D with the given \a parent.
 */
 QGraphicsRotation3D::QGraphicsRotation3D(QObject *parent)
     : QGraphicsRotation(*new QGraphicsRotation3DPrivate, parent)
@@ -407,7 +495,7 @@ QGraphicsRotation3D::QGraphicsRotation3D(QObject *parent)
 }
 
 /*!
-  Destroys the object
+    Destroys the 3D graphics rotation.
 */
 QGraphicsRotation3D::~QGraphicsRotation3D()
 {
@@ -415,15 +503,22 @@ QGraphicsRotation3D::~QGraphicsRotation3D()
 
 /*!
     \property QGraphicsRotation3D::axis
+    \brief a rotation axis, specified by a vector in 3D space.
+
+    This can be any axis in 3D space. By default the axis is (0, 0, 1),
+    which is aligned with the Z axis and provides the same behavior
+    for the rotation angle as QGraphicsRotation. If you provide another
+    axis, QGraphicsRotation3D will provide a transformation that rotates
+    around this axis. For example, if you would like to rotate an item
+    around its X axis, you could pass (1, 0, 0) as the axis.
 
-    A rotation axis is specified by a vector in 3D space.
+    \sa QTransform, QGraphicsRotation::angle
 */
 QVector3D QGraphicsRotation3D::axis()
 {
     Q_D(QGraphicsRotation3D);
     return d->axis;
 }
-
 void QGraphicsRotation3D::setAxis(const QVector3D &axis)
 {
     Q_D(QGraphicsRotation3D);
@@ -431,17 +526,10 @@ void QGraphicsRotation3D::setAxis(const QVector3D &axis)
     update();
 }
 
-/*!
-  \fn void QGraphicsRotation3D::axisChanged()
-
-  This signal is emitted whenever the axis of the object
-  changes.
-*/
-
-const qreal inv_dist_to_plane = 1. / 1024.;
+static const qreal inv_dist_to_plane = 1. / 1024.;
 
 /*!
-  \reimp
+    \reimp
 */
 void QGraphicsRotation3D::applyTo(QTransform *t) const
 {
@@ -474,6 +562,12 @@ void QGraphicsRotation3D::applyTo(QTransform *t) const
     t->translate(-d->origin.x(), -d->origin.y());
 }
 
+/*!
+    \fn void QGraphicsRotation3D::axisChanged()
+
+    This signal is emitted whenever the axis of the object changes.
+*/
+
 #include "moc_qgraphicstransform.cpp"
 
 QT_END_NAMESPACE
diff --git a/src/gui/graphicsview/qgraphicstransform.h b/src/gui/graphicsview/qgraphicstransform.h
index b5d8d84..d7c07d0 100644
--- a/src/gui/graphicsview/qgraphicstransform.h
+++ b/src/gui/graphicsview/qgraphicstransform.h
@@ -70,6 +70,7 @@ protected Q_SLOTS:
 
 protected:
     QGraphicsTransform(QGraphicsTransformPrivate &p, QObject *parent);
+
 private:
     friend class QGraphicsItem;
     friend class QGraphicsItemPrivate;