Augment Particle Docs

Just filling out some sections.

Change-Id: I5ffe1bf558a556035745ddeae058b0b2f7ecf258
Reviewed-on: http://codereview.qt-project.org/4071
Reviewed-by: Qt Sanity Bot <qt_sanity_bot@ovi.com>
Reviewed-by: Martin Jones <martin.jones@nokia.com>

9 files changed, 238 insertions, 7 deletions

diff --git a/doc/src/declarative/particles.qdoc b/doc/src/declarative/particles.qdoc
index 9f1da69eb8..4f84db2ef2 100644
--- a/doc/src/declarative/particles.qdoc
+++ b/doc/src/declarative/particles.qdoc
@@ -33,7 +33,7 @@
 
   This QML module contains a particle system for Qt Quick.
 
-  For a simple overview of how the system can be used, see \l{qml-particles.html}{Using the Qt Quick Particle System}.
+  For a simple overview of how the system can be used, see \l{qml-particlesystem.html}{Using the Qt Quick Particle System}.
 
 */
 
diff --git a/src/declarative/particles/qsgfriction.cpp b/src/declarative/particles/qsgfriction.cpp
index 6baeaf6c3b..031fc896bf 100644
--- a/src/declarative/particles/qsgfriction.cpp
+++ b/src/declarative/particles/qsgfriction.cpp
@@ -51,6 +51,8 @@ QT_BEGIN_NAMESPACE
 
 /*!
     \qmlproperty real QtQuick.Particles2::Friction::factor
+
+    A drag will be applied to moving objects which is this factor of their current velocity.
 */
 
 QSGFrictionAffector::QSGFrictionAffector(QSGItem *parent) :
diff --git a/src/declarative/particles/qsggravity.cpp b/src/declarative/particles/qsggravity.cpp
index 1de2a0e014..d775b49d6f 100644
--- a/src/declarative/particles/qsggravity.cpp
+++ b/src/declarative/particles/qsggravity.cpp
@@ -51,14 +51,22 @@ const qreal CONV = 0.017453292520444443;
 
     This element will set the acceleration of all affected particles to a vector of
     the specified magnitude in the specified angle.
+
+    This element models the gravity of a massive object whose center of
+    gravity is far away (and thus the gravitational pull is effectively constant
+    across the scene). To model the gravity of an object near or inside the scene,
+    use PointAttractor.
 */
 
 /*!
     \qmlproperty real QtQuick.Particles2::Gravity::acceleration
 
+    Pixels per second that objects will be accelerated by.
 */
 /*!
     \qmlproperty real QtQuick.Particles2::Gravity::angle
+
+    Angle of acceleration.
 */
 
 QSGGravityAffector::QSGGravityAffector(QSGItem *parent) :
diff --git a/src/declarative/particles/qsgimageparticle.cpp b/src/declarative/particles/qsgimageparticle.cpp
index 5e0e97797f..b31d763f82 100644
--- a/src/declarative/particles/qsgimageparticle.cpp
+++ b/src/declarative/particles/qsgimageparticle.cpp
@@ -447,68 +447,157 @@ void fillUniformArrayFromImage(float* array, const QImage& img, int size)
 
     This element renders a logical particle as an image. The image can be
         - colorized
-        - roatated
+        - rotated
         - deformed
         - a sprite-based animation
 */
 /*!
     \qmlproperty url QtQuick.Particles2::ImageParticle::source
+
+    The source image to be used.
+
+    If the image is a sprite animation, use the sprite property instead.
+*/
+/*!
+    \qmlproperty list<Sprite> QtQuick.Particles2::ImageParticle::sprites
+
+    The sprite or sprites used to draw this particle.
 */
 /*!
     \qmlproperty url QtQuick.Particles2::ImageParticle::colorTable
+
+    An image whose color will be used as a 1D texture to determine color over life. E.g. when
+    the particle is halfway through its lifetime, it will have the color specified halfway
+    across the image.
+
+    This color is blended with the color property and the color of the source image.
 */
 /*!
     \qmlproperty url QtQuick.Particles2::ImageParticle::sizeTable
 
-    Note that currently sizeTable is ignored for sprite particles.
+    An image whose opacity will be used as a 1D texture to determine size over life.
+
+    This property is expected to be removed shortly, in favor of custom easing curves to determine size over life.
 */
 /*!
     \qmlproperty url QtQuick.Particles2::ImageParticle::opacityTable
+
+    An image whose opacity will be used as a 1D texture to determine size over life.
+
+    This property is expected to be removed shortly, in favor of custom easing curves to determine opacity over life.
 */
 /*!
     \qmlproperty color QtQuick.Particles2::ImageParticle::color
+
+    If a color is specified, the provided image will be colorized with it.
+
+    Default is white (no change).
 */
 /*!
     \qmlproperty real QtQuick.Particles2::ImageParticle::colorVariation
+
+    This number represents the color variation applied to individual particles.
+    Setting colorVariation is the same as setting redVariation, greenVariation,
+    and blueVariation to the same number.
+
+    Each channel can vary between particle by up to colorVariation from its usual color.
+
+    Color is measured, per channel, from 0.0 to 1.0.
+
+    Default is 0.0
 */
 /*!
     \qmlproperty real QtQuick.Particles2::ImageParticle::redVariation
+    The variation in the red color channel between particles.
+
+    Color is measured, per channel, from 0.0 to 1.0.
+
+    Default is 0.0
 */
 /*!
     \qmlproperty real QtQuick.Particles2::ImageParticle::greenVariation
+    The variation in the green color channel between particles.
+
+    Color is measured, per channel, from 0.0 to 1.0.
+
+    Default is 0.0
 */
 /*!
     \qmlproperty real QtQuick.Particles2::ImageParticle::blueVariation
+    The variation in the blue color channel between particles.
+
+    Color is measured, per channel, from 0.0 to 1.0.
+
+    Default is 0.0
 */
 /*!
     \qmlproperty real QtQuick.Particles2::ImageParticle::alpha
+    An alpha to be applied to the image. This value is multiplied by the value in
+    the image, and the value in the color property.
+
+    Particles have additive blending, so lower alpha on single particles leads
+    to stronger effects when multiple particles overlap.
+
+    Alpha is measured from 0.0 to 1.0.
+
+    Default is 1.0
 */
 /*!
     \qmlproperty real QtQuick.Particles2::ImageParticle::alphaVariation
+    The variation in the alpha channel between particles.
+
+    Alpha is measured from 0.0 to 1.0.
+
+    Default is 0.0
 */
 /*!
     \qmlproperty real QtQuick.Particles2::ImageParticle::rotation
+
+    If set the image will be rotated by this many degrees before it is drawn.
+
+    The particle coordinates are not transformed.
 */
 /*!
     \qmlproperty real QtQuick.Particles2::ImageParticle::rotationVariation
+
+    If set the rotation of individual particles will vary by up to this much
+    between particles.
+
 */
 /*!
     \qmlproperty real QtQuick.Particles2::ImageParticle::rotationSpeed
+
+    If set particles will rotate at this speed in degrees/second.
 */
 /*!
     \qmlproperty real QtQuick.Particles2::ImageParticle::rotationSpeedVariation
+
+    If set the rotationSpeed of individual particles will vary by up to this much
+    between particles.
+
 */
 /*!
     \qmlproperty bool QtQuick.Particles2::ImageParticle::autoRotation
+
+    If set to true then a rotation will be applied on top of the particles rotation, so
+    that it faces the direction of travel. So to face away from the direction of travel,
+    set autoRotation to true and rotation to 180.
+
+    Default is false
 */
 /*!
     \qmlproperty StochasticDirection QtQuick.Particles2::ImageParticle::xVector
+
+    Allows you to deform the particle image when drawn. The rectangular image will
+    be deformed so that the horizontal sides are in the shape of this vector instead
+    of (1,0).
 */
 /*!
     \qmlproperty StochasticDirection QtQuick.Particles2::ImageParticle::yVector
-*/
-/*!
-    \qmlproperty list<Sprite> QtQuick.Particles2::ImageParticle::sprites
+
+    Allows you to deform the particle image when drawn. The rectangular image will
+    be deformed so that the vertical sides are in the shape of this vector instead
+    of (0,1).
 */
 /*!
     \qmlproperty EntryEffect QtQuick.Particles2::ImageParticle::entryEffect
diff --git a/src/declarative/particles/qsgitemparticle.cpp b/src/declarative/particles/qsgitemparticle.cpp
index 65407fabf8..c330880980 100644
--- a/src/declarative/particles/qsgitemparticle.cpp
+++ b/src/declarative/particles/qsgitemparticle.cpp
@@ -56,6 +56,49 @@ QT_BEGIN_NAMESPACE
 
 */
 
+
+/*!
+    \qmlmethod void QtQuick.Particles2::ItemParticle::freeze(Item item)
+
+    Suspends the flow of time for the logical particle which item represents, allowing you to control its movement.
+*/
+
+/*!
+    \qmlmethod void QtQuick.Particles2::ItemParticle::unfreeze(Item item)
+
+    Restarts the flow of time for the logical particle which item represents, allowing it to be moved by the particle system again.
+*/
+
+/*!
+    \qmlmethod void QtQuick.Particles2::ItemParticle::take(Item item, bool prioritize)
+
+    Asks the ItemParticle to take over control of item. It will be emitted when there is a logical particle available.
+
+    By default items form a queue when waiting for a logical particle, but if prioritize is true then it will go immediately to the
+    head of the queue.
+*/
+/*!
+    \qmlmethod void QtQuick.Particles2::ItemParticle::give(Item item)
+
+    Orders the ItemParticle to give you control of the item. It will cease controlling it and the item will lose its association to the logical particle.
+*/
+
+/*!
+    \qmlproperty bool QtQuick.Particles2::ItemParticle::fade
+
+    If true, the item will automatically be faded in and out
+    at the ends of its lifetime. If false, you will have to
+    implement any entry effect yourself.
+
+    Default is true.
+*/
+/*!
+    \qmlproperty Component QtQuick.Particles2::ItemParticle::delegate
+
+    An instance of the delegate will be created for every logical
+    particle, and moved along with it.
+*/
+
 QSGItemParticle::QSGItemParticle(QSGItem *parent) :
     QSGParticlePainter(parent), m_fade(true), m_delegate(0)
 {
diff --git a/src/declarative/particles/qsgmaskextruder.cpp b/src/declarative/particles/qsgmaskextruder.cpp
index 4f8b89a639..6facfac353 100644
--- a/src/declarative/particles/qsgmaskextruder.cpp
+++ b/src/declarative/particles/qsgmaskextruder.cpp
@@ -52,6 +52,9 @@ QT_BEGIN_NAMESPACE
 */
 /*!
     \qmlproperty url QtQuick.Particles2::MaskShape::source
+
+    The image to use as the mask. Areas with non-zero opacity
+    will be considered inside the shape.
 */
 
 
diff --git a/src/declarative/particles/qsgmodelparticle.cpp b/src/declarative/particles/qsgmodelparticle.cpp
index 2646864283..c013d726a3 100644
--- a/src/declarative/particles/qsgmodelparticle.cpp
+++ b/src/declarative/particles/qsgmodelparticle.cpp
@@ -55,6 +55,43 @@ QT_BEGIN_NAMESPACE
 */
 
 
+/*!
+    \qmlmethod void QtQuick.Particles2::ModelParticle::freeze(Item item)
+
+    Suspends the flow of time for the logical particle which item represents, allowing you to control its movement.
+*/
+
+/*!
+    \qmlmethod void QtQuick.Particles2::ModelParticle::unfreeze(Item item)
+
+    Restarts the flow of time for the logical particle which item represents, allowing it to be moved by the particle system again.
+*/
+
+/*!
+    \qmlproperty bool QtQuick.Particles2::ModelParticle::fade
+
+    If true, the item will automatically be faded in and out
+    at the ends of its lifetime. If false, you will have to
+    implement any entry effect yourself.
+
+    Default is true.
+*/
+
+/*!
+    \qmlproperty model QtQuick.Particles2::ModelParticle::model
+
+    The model to use as a data source. Every time a particle is
+    emitted, the next model entry will be used with a delegate
+    to visualize it.
+*/
+
+/*!
+    \qmlproperty Component QtQuick.Particles2::ModelParticle::delegate
+
+    An instance of the delegate will be created for every model
+    entry, and moved along with it.
+*/
+
 QSGModelParticle::QSGModelParticle(QSGItem *parent) :
     QSGParticlePainter(parent), m_ownModel(false), m_comp(0), m_model(0), m_fade(true), m_modelCount(0)
 {
diff --git a/src/declarative/particles/qsgparticleaffector.cpp b/src/declarative/particles/qsgparticleaffector.cpp
index 83912898cf..067aa1d84b 100644
--- a/src/declarative/particles/qsgparticleaffector.cpp
+++ b/src/declarative/particles/qsgparticleaffector.cpp
@@ -112,6 +112,16 @@ QT_BEGIN_NAMESPACE
 
     dt is the time since the last time it was affected. Use dt to normalize
     trajectory manipulations to real time.
+
+    This handler is usually not available on inherited types.
+*/
+/*!
+    \qmlsignal QtQuick.Particles2::Affector::affected(x, y)
+
+    This handler is called when a particle is selected to be affected. It will
+    only be called if signal is set to true.
+
+    x,y is the particles current position.
 */
 QSGParticleAffector::QSGParticleAffector(QSGItem *parent) :
     QSGItem(parent), m_needsReset(false), m_system(0), m_active(true)
diff --git a/src/declarative/particles/qsgpointattractor.cpp b/src/declarative/particles/qsgpointattractor.cpp
index 21eaeaac12..c916e4da94 100644
--- a/src/declarative/particles/qsgpointattractor.cpp
+++ b/src/declarative/particles/qsgpointattractor.cpp
@@ -51,9 +51,48 @@ QT_BEGIN_NAMESPACE
 
     Note that the size and position of this element affects which particles it affects.
     The size of the point attracted to is always 0x0, and the location of that point
-    is specified by the x and y properties that badly need renaming.
+    is specified by the pointX and pointY properties.
 
+    Note that PointAttractor has the standard Item x,y,width and height properties.
+    Like other affectors, these represent the affected area. They
+    do not represent the 0x0 point which is the target of the attraction.
+
+*/
+
+
+/*!
+    \qmlproperty real QtQuick.Particles2::PointAttractor::pointX
+*/
+/*!
+    \qmlproperty real QtQuick.Particles2::PointAttractor::pointY
+*/
+/*!
+    \qmlproperty real QtQuick.Particles2::PointAttractor::strength
 */
+/*!
+    \qmlproperty PhysicsAffects QtQuick.Particles2::PointAttractor::physics
+
+    What attribute of particles is directly affected.
+    \list
+    \o PointAttractor.Position
+    \o PointAttractor.Velocity
+    \o PointAttractor.Acceleration
+    \endlist
+*/
+/*!
+    \qmlproperty Proportion QtQuick.Particles2::PointAttractor::proportionalToDistance
+
+    How the distance from the particle to the point affects the strength of the attraction.
+
+    \list
+    \o PointAttractor.Constant
+    \o PointAttractor.Linear
+    \o PointAttractor.InverseLinear
+    \o PointAttractor.Quadratic
+    \o PointAttractor.InverseQuadratic
+    \endlist
+*/
+
 
 QSGPointAttractorAffector::QSGPointAttractorAffector(QSGItem *parent) :
     QSGParticleAffector(parent), m_strength(0.0), m_x(0), m_y(0)