Add docs for animations

Also updated docs of other classes due to property changes.

Change-Id: I1b1d44ad574ebb6ddf2ce7de5fe888c7b02a450b
Reviewed-by: Sean Harmer <sean.harmer@kdab.com>

8 files changed, 763 insertions, 9 deletions

diff --git a/src/animation/frontend/qabstractanimation.cpp b/src/animation/frontend/qabstractanimation.cpp
index 6f5aa05d8..efac3f5ec 100644
--- a/src/animation/frontend/qabstractanimation.cpp
+++ b/src/animation/frontend/qabstractanimation.cpp
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2016 The Qt Company Ltd.
+** Copyright (C) 2017 The Qt Company Ltd.
 ** Contact: http://www.qt.io/licensing/
 **
 ** This file is part of the Qt3D module of the Qt Toolkit.
@@ -41,6 +41,80 @@ QT_BEGIN_NAMESPACE
 
 namespace Qt3DAnimation {
 
+/*!
+    \class Qt3DAnimation::QAbstractAnimation
+    \brief An abstract base class for Qt3D animations
+    \inmodule Qt3DAnimation
+    \since 5.9
+    \inherits QObject
+
+    Qt3DAnimation::QAbstractAnimation is an abstract base class for all animations.
+    Qt3DAnimation::QAbstractAnimation can not be directly instantiated, but rather
+    through its subclasses. QAbstractAnimation specifies common properties
+    for all Qt3D animations, such as animation name and type, current position and animation
+    duration, while leaving the actual animating for the subclasses.
+*/
+
+/*!
+    \qmltype AbstractAnimation
+    \brief An abstract base type for Qt3D animations
+    \inqmlmodule Qt3D.Animation
+    \since 5.9
+    \instantiates Qt3DAnimation::QAbstractAnimation
+
+    AbstractAnimation is an abstract base type for all animations.
+    AbstractAnimation can not be directly instantiated, but rather
+    through its subtypes. AbstractAnimation specifies common properties
+    for all Qt3D animations, such as animation type, current position and animation
+    duration, while leaving the actual animating for the subtypes.
+*/
+/*!
+    \enum QAbstractAnimation::AnimationType
+
+    This enumeration specifies the type of the animation
+    \value KeyframeAnimation Simple keyframe animation implementation for QTransform
+    \value MorphingAnimation Blend-shape morphing animation
+    \value VertexBlendAnimation Vertex-blend animation
+*/
+/*!
+    \property Qt3DAnimation::QAbstractAnimation::animationName
+    Holds the name of the animation.
+*/
+/*!
+    \property Qt3DAnimation::QAbstractAnimation::animationType
+    Holds the type of the animation.
+*/
+/*!
+    \property Qt3DAnimation::QAbstractAnimation::position
+    Holds the current position of the animation.
+*/
+/*!
+    \property Qt3DAnimation::QAbstractAnimation::duration
+    Holds the duration of the animation.
+*/
+
+/*!
+    \qmlproperty string AbstractAnimation::animationName
+    Holds the name of the animation.
+*/
+/*!
+    \qmlproperty enumeration AbstractAnimation::animationType
+    Holds the type of the animation.
+    \list
+    \li KeyframeAnimation
+    \li MorphingAnimation
+    \li VertexBlendAnimation
+    \endlist
+*/
+/*!
+    \qmlproperty real AbstractAnimation::position
+    Holds the current position of the animation.
+*/
+/*!
+    \qmlproperty real AbstractAnimation::duration
+    Holds the duration of the animation.
+*/
+
 QAbstractAnimationPrivate::QAbstractAnimationPrivate(QAbstractAnimation::AnimationType type)
     : QObjectPrivate()
     , m_animationType(type)
@@ -98,6 +172,9 @@ void QAbstractAnimation::setPosition(float position)
     }
 }
 
+/*!
+    Sets the \a duration of the animation.
+*/
 void QAbstractAnimation::setDuration(float duration)
 {
     Q_D(QAbstractAnimation);
diff --git a/src/animation/frontend/qabstractanimation.h b/src/animation/frontend/qabstractanimation.h
index af70399b1..0c6fe865e 100644
--- a/src/animation/frontend/qabstractanimation.h
+++ b/src/animation/frontend/qabstractanimation.h
@@ -62,6 +62,7 @@ public:
         MorphingAnimation = 2,
         VertexBlendAnimation = 3,
     };
+    Q_ENUM(AnimationType)
 
     QString animationName() const;
     QAbstractAnimation::AnimationType animationType() const;
diff --git a/src/animation/frontend/qanimationcontroller.cpp b/src/animation/frontend/qanimationcontroller.cpp
index a735ba7ed..5df2c713a 100644
--- a/src/animation/frontend/qanimationcontroller.cpp
+++ b/src/animation/frontend/qanimationcontroller.cpp
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2016 The Qt Company Ltd.
+** Copyright (C) 2017 The Qt Company Ltd.
 ** Contact: http://www.qt.io/licensing/
 **
 ** This file is part of the Qt3D module of the Qt Toolkit.
@@ -43,6 +43,117 @@ QT_BEGIN_NAMESPACE
 
 namespace Qt3DAnimation {
 
+/*!
+    \class Qt3DAnimation::QAnimationController
+    \brief A controller class for animations
+    \inmodule Qt3DAnimation
+    \since 5.9
+    \inherits QObject
+
+    Qt3DAnimation::QAnimationController class controls the selection and playback of animations.
+    The class can be used to find all animations from Qt3DCore::QEntity tree and create
+    \l {Qt3DAnimation::QAnimationGroup} {QAnimationGroups} from the animations with the same name.
+    The user can select which animation group is currently controlled with the animation
+    controller by setting the active animation. The animation position is then propagated to
+    that group after scaling and offsetting the provided position value with the
+    positionScale and positionOffset values.
+
+    \note that the animation controller doesn't have internal timer, but instead the user
+    is responsible for updating the position property in timely manner.
+*/
+
+/*!
+    \qmltype AnimationController
+    \brief A controller type for animations
+    \inqmlmodule Qt3D.Animation
+    \since 5.9
+    \instantiates Qt3DAnimation::QAnimationController
+
+    AnimationController type controls the selection and playback of animations.
+    The type can be used to find all animations from Entity tree and create
+    \l {AnimationGroup} {AnimationGroups} from the animations with the same name.
+    The user can select which animation group is currently controlled with the animation
+    controller by setting the active animation. The animation position is then propagated to
+    that group after scaling and offsetting the provided position value with the
+    positionScale and positionOffset values.
+
+    \note that the animation controller doesn't have internal timer, but instead the user
+    is responsible for updating the position property in timely manner.
+*/
+
+/*!
+    \property Qt3DAnimation::QAnimationController::activeAnimationGroup
+    Holds the currectly active animation group.
+*/
+/*!
+    \property Qt3DAnimation::QAnimationController::position
+    Holds the current position of the animation. When the position is set,
+    it is scaled and offset with positionScale/positionOffset and propagated
+    to the active animation group.
+*/
+/*!
+    \property Qt3DAnimation::QAnimationController::positionScale
+    Holds the position scale of the animation.
+*/
+/*!
+    \property Qt3DAnimation::QAnimationController::positionOffset
+    Holds the position offset of the animation.
+*/
+/*!
+    \property Qt3DAnimation::QAnimationController::entity
+    Holds the entity animations are gathered and grouped from. If the controller already
+    holds animations, they are cleared.
+*/
+/*!
+    \property Qt3DAnimation::QAnimationController::recursive
+    Holds whether the recursively search the entity tree when gathering animations from the entity.
+    If set to true, the animations are searched also from the child entities of the entity.
+    If set to false, only the entity passed to the controller is searched.
+*/
+
+/*!
+    \qmlproperty int AnimationController::activeAnimationGroup
+    Holds the currectly active animation group.
+*/
+/*!
+    \qmlproperty real AnimationController::position
+    Holds the current position of the animation. When the position is set,
+    it is scaled and offset with positionScale/positionOffset and propagated
+    to the active animation group.
+*/
+/*!
+    \qmlproperty real AnimationController::positionScale
+    Holds the position scale of the animation.
+*/
+/*!
+    \qmlproperty real AnimationController::positionOffset
+    Holds the position offset of the animation.
+*/
+/*!
+    \qmlproperty Entity AnimationController::entity
+    Holds the entity animations are gathered and grouped from. If the controller already
+    holds animations, they are cleared.
+*/
+/*!
+    \qmlproperty bool AnimationController::recursive
+    Holds whether the recursively search the entity tree when gathering animations from the entity.
+    If set to true, the animations are searched also from the child entities of the entity.
+    If set to false, only the entity passed to the controller is searched.
+*/
+/*!
+    \qmlproperty list<AnimationGroup> AnimationController::animationGroups
+    Holds the list of animation groups in the controller.
+*/
+/*!
+    \qmlmethod int Qt3D.Animation::AnimationController::getAnimationIndex(name)
+    Returns the index of the animation with \a name. Returns -1 if no AnimationGroup
+    with the given name is found.
+*/
+/*!
+    \qmlmethod AnimationGroup Qt3D.Animation::AnimationController::getGroup(index)
+    Returns the AnimationGroup with the given \a index.
+*/
+
 QAnimationControllerPrivate::QAnimationControllerPrivate()
     : QObjectPrivate()
     , m_activeAnimationGroup(0)
@@ -106,12 +217,18 @@ void QAnimationControllerPrivate::clearAnimations()
     m_activeAnimationGroup = 0;
 }
 
+/*!
+    Constructs a new QAnimationController with \a parent.
+ */
 QAnimationController::QAnimationController(QObject *parent)
     : QObject(*new QAnimationControllerPrivate, parent)
 {
 
 }
 
+/*!
+    Returns the list of animation groups the conroller is currently holding.
+ */
 QVector<QAnimationGroup *> QAnimationController::animationGroupList()
 {
     Q_D(QAnimationController);
@@ -154,7 +271,10 @@ bool QAnimationController::recursive() const
     return d->m_recursive;
 }
 
-void QAnimationController::setAnimationGroups(const QVector<QAnimationGroup *> &animationGroups)
+/*!
+    Sets the \a animationGroups for the controller. Old groups are cleared.
+ */
+void QAnimationController::setAnimationGroups(const QVector<Qt3DAnimation::QAnimationGroup *> &animationGroups)
 {
     Q_D(QAnimationController);
     d->m_animationGroups = animationGroups;
@@ -163,6 +283,9 @@ void QAnimationController::setAnimationGroups(const QVector<QAnimationGroup *> &
     d->updatePosition(d->m_position);
 }
 
+/*!
+    Adds the given \a animationGroup to the controller.
+ */
 void QAnimationController::addAnimationGroup(Qt3DAnimation::QAnimationGroup *animationGroup)
 {
     Q_D(QAnimationController);
@@ -170,6 +293,9 @@ void QAnimationController::addAnimationGroup(Qt3DAnimation::QAnimationGroup *ani
         d->m_animationGroups.push_back(animationGroup);
 }
 
+/*!
+    Removes the given \a animationGroup from the controller.
+ */
 void QAnimationController::removeAnimationGroup(Qt3DAnimation::QAnimationGroup *animationGroup)
 {
     Q_D(QAnimationController);
@@ -236,6 +362,10 @@ void QAnimationController::setRecursive(bool recursive)
     }
 }
 
+/*!
+    Returns the index of the animation with \a name. Returns -1 if no AnimationGroup
+    with the given name is found.
+*/
 int QAnimationController::getAnimationIndex(const QString &name) const
 {
     Q_D(const QAnimationController);
@@ -246,6 +376,9 @@ int QAnimationController::getAnimationIndex(const QString &name) const
     return -1;
 }
 
+/*!
+    Returns the AnimationGroup with the given \a index.
+*/
 QAnimationGroup *QAnimationController::getGroup(int index) const
 {
     Q_D(const QAnimationController);
diff --git a/src/animation/frontend/qanimationgroup.cpp b/src/animation/frontend/qanimationgroup.cpp
index 91da1ead3..07d0fadc5 100644
--- a/src/animation/frontend/qanimationgroup.cpp
+++ b/src/animation/frontend/qanimationgroup.cpp
@@ -41,6 +41,63 @@ QT_BEGIN_NAMESPACE
 
 namespace Qt3DAnimation {
 
+/*!
+    \class Qt3DAnimation::QAnimationGroup
+    \brief A class grouping animations together
+    \inmodule Qt3DAnimation
+    \since 5.9
+    \inherits QObject
+
+    Qt3DAnimation::QAnimationGroup class is used to group multiple animations so that
+    they can act as one animation. The position set to the group is also set to
+    all animations in a group. The duration is the maximum of the individual animations.
+    The animations can be any supported animation type and do not have to have the same name.
+*/
+/*!
+    \qmltype AnimationGroup
+    \brief A type grouping animations together
+    \inqmlmodule Qt3D.Animation
+    \since 5.9
+    \inherits QObject
+
+    AnimationGroup type is used to group multiple animations so that
+    they can act as one animation. The position set to the group is also set to
+    all animations in a group. The duration is the maximum of the individual animations.
+    The animations can be any supported animation type and do not have to have the same name.
+*/
+
+/*!
+    \property Qt3DAnimation::QAnimationGroup::name
+    Holds the name of the animation group.
+*/
+/*!
+    \property Qt3DAnimation::QAnimationGroup::position
+    Holds the animation position.
+*/
+/*!
+    \property Qt3DAnimation::QAnimationGroup::duration
+    Holds the maximum duration of the animations in the group.
+    \readonly
+*/
+
+/*!
+    \qmlproperty string AnimationGroup::name
+    Holds the name of the animation group.
+*/
+/*!
+    \qmlproperty real AnimationGroup::position
+    Holds the animation position.
+*/
+/*!
+    \qmlproperty real AnimationGroup::duration
+    Holds the maximum duration of the animations in the group.
+    \readonly
+*/
+/*!
+    \qmlproperty list<AbstractAnimation> AnimationGroup::animations
+    Holds the list of animations in the animation group.
+*/
+
 QAnimationGroupPrivate::QAnimationGroupPrivate()
     : QObjectPrivate()
     , m_position(0.0f)
@@ -56,6 +113,9 @@ void QAnimationGroupPrivate::updatePosition(float position)
         aa->setPosition(position);
 }
 
+/*!
+    Constructs an QAnimationGroup with \a parent.
+*/
 QAnimationGroup::QAnimationGroup(QObject *parent)
     : QObject(*new QAnimationGroupPrivate, parent)
 {
@@ -68,6 +128,9 @@ QString QAnimationGroup::name() const
     return d->m_name;
 }
 
+/*!
+    Returns the list of animations in the group.
+ */
 QVector<Qt3DAnimation::QAbstractAnimation *> QAnimationGroup::animationList()
 {
     Q_D(QAnimationGroup);
@@ -95,6 +158,9 @@ void QAnimationGroup::setName(const QString &name)
     }
 }
 
+/*!
+    Sets the \a animations to the group. Old animations are removed.
+ */
 void QAnimationGroup::setAnimations(const QVector<Qt3DAnimation::QAbstractAnimation *> &animations)
 {
     Q_D(QAnimationGroup);
@@ -104,11 +170,32 @@ void QAnimationGroup::setAnimations(const QVector<Qt3DAnimation::QAbstractAnimat
         d->m_duration = qMax(d->m_duration, a->duration());
 }
 
-void QAnimationGroup::addAnimation(QAbstractAnimation *animation)
+/*!
+    Adds new \a animation to the group.
+ */
+void QAnimationGroup::addAnimation(Qt3DAnimation::QAbstractAnimation *animation)
 {
     Q_D(QAnimationGroup);
-    d->m_animations.push_back(animation);
-    d->m_duration = qMax(d->m_duration, animation->duration());
+    if (!d->m_animations.contains(animation)) {
+        d->m_animations.push_back(animation);
+        d->m_duration = qMax(d->m_duration, animation->duration());
+    }
+}
+
+/*!
+    Removes \a animation from the group.
+ */
+void QAnimationGroup::removeAnimation(Qt3DAnimation::QAbstractAnimation *animation)
+{
+    Q_D(QAnimationGroup);
+    if (!d->m_animations.contains(animation)) {
+        d->m_animations.removeAll(animation);
+        if (qFuzzyCompare(d->m_duration, animation->duration())) {
+            d->m_duration = 0.0f;
+            for (const Qt3DAnimation::QAbstractAnimation *a : d->m_animations)
+                d->m_duration = qMax(d->m_duration, a->duration());
+        }
+    }
 }
 
 void QAnimationGroup::setPosition(float position)
diff --git a/src/animation/frontend/qkeyframeanimation.cpp b/src/animation/frontend/qkeyframeanimation.cpp
index 981437d28..0b17265a6 100644
--- a/src/animation/frontend/qkeyframeanimation.cpp
+++ b/src/animation/frontend/qkeyframeanimation.cpp
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2016 The Qt Company Ltd.
+** Copyright (C) 2017 The Qt Company Ltd.
 ** Contact: http://www.qt.io/licensing/
 **
 ** This file is part of the Qt3D module of the Qt Toolkit.
@@ -43,6 +43,118 @@ QT_BEGIN_NAMESPACE
 
 namespace Qt3DAnimation {
 
+/*!
+    \class Qt3DAnimation::QKeyframeAnimation
+    \brief A class implementing simple keyframe animation to a QTransform
+    \inmodule Qt3DAnimation
+    \since 5.9
+    \inherits Qt3DAnimation::QAbstractAnimation
+
+    A Qt3DAnimation::QKeyframeAnimation class implements simple keyframe animation
+    that can be used to animate \l QTransform. The keyframes consists of multiple
+    timed QTransforms, which are interpolated and applied to the target \l QTransform.
+    \l QEasingCurve is used between keyframes to control the interpolator. RepeatMode
+    can be set for when the position set to the QKeyframeAnimation is below or above
+    the values defined in the keyframe positions.
+*/
+
+/*!
+    \qmltype KeyframeAnimation
+    \brief A type implementing simple keyframe animation to a Transform
+    \inqmlmodule Qt3D.Animation
+    \since 5.9
+    \inherits AbstractAnimation
+    \instantiates Qt3DAnimation::QKeyframeAnimation
+
+    A KeyframeAnimation type implements simple keyframe animation
+    that can be used to animate \l Transform. The keyframes consists of multiple
+    timed \l {Qt3D.Render::Transform}{Transforms}, which are interpolated and applied
+    to the target Transform. EasingCurve is used between keyframes to control
+    the interpolator. RepeatMode can be set for when the position set to the
+    KeyframeAnimation is less or or greater than the values defined in the keyframe positions.
+*/
+
+/*!
+    \property Qt3DAnimation::QKeyframeAnimation::framePositions
+    Holds the positions of the keyframes. Each position in the list specifies the position
+    of the corresponding keyframe with the same index. The values must be in an ascending order.
+    Values can be positive or negative and do not have any predefined unit.
+*/
+/*!
+    \property Qt3DAnimation::QKeyframeAnimation::target
+    Holds the target QTransform the animation is applied to.
+*/
+/*!
+    \property Qt3DAnimation::QKeyframeAnimation::easing
+    Holds the easing curve of the interpolator between keyframes.
+*/
+/*!
+    \property Qt3DAnimation::QKeyframeAnimation::targetName
+    Holds the name of the target transform. This is a convenience property making it
+    easier to match the target transform to the keyframe animation. The name
+    is usually same as the name of the parent entity of the target transform, but
+    does not have to be.
+*/
+/*!
+    \property Qt3DAnimation::QKeyframeAnimation::startMode
+    Holds the repeat mode for the position values less than the first frame position.
+*/
+/*!
+    \property Qt3DAnimation::QKeyframeAnimation::endMode
+    Holds the repeat mode for the position values greater than the last frame position.
+*/
+/*!
+    \enum QKeyframeAnimation::RepeatMode
+
+    This enumeration specifies how position values outside keyframe values are handled.
+    \value None The animation is not applied to the target transform.
+    \value Constant The edge keyframe value is used.
+    \value Repeat The animation is repeated.
+*/
+/*!
+    \qmlproperty list<real> KeyframeAnimation::framePositions
+    Holds the positions of the keyframes. Each position in the list specifies the position
+    of the corresponding keyframe. The values must be in an ascending order. Values can
+    be positive or negative and do not have any predefined unit.
+*/
+/*!
+    \qmlproperty Transform KeyframeAnimation::target
+    Holds the target Transform the animation is applied to.
+*/
+/*!
+    \qmlproperty EasingCurve KeyframeAnimation::easing
+    Holds the easing curve of the interpolator between keyframes.
+*/
+/*!
+    \qmlproperty string KeyframeAnimation::targetName
+    Holds the name of the target transform. This is a convenience property making it
+    easier to match the target transform to the keyframe animation. The name
+    is usually same as the name of the parent entity of the target transform, but
+    does not have to be.
+*/
+/*!
+    \qmlproperty enumeration KeyframeAnimation::startMode
+    Holds the repeat mode for the position values less than the first frame position.
+    \list
+    \li None
+    \li Constant
+    \li Repeat
+    \endlist
+*/
+/*!
+    \qmlproperty enumeration KeyframeAnimation::endMode
+    Holds the repeat mode for the position values greater than the last frame position.
+    \list
+    \li None
+    \li Constant
+    \li Repeat
+    \endlist
+*/
+/*!
+    \qmlproperty list<Transform> KeyframeAnimation::keyframes
+    Holds the list of keyframes in the keyframe animation.
+*/
+
 QKeyframeAnimationPrivate::QKeyframeAnimationPrivate()
     : QAbstractAnimationPrivate(QAbstractAnimation::KeyframeAnimation)
     , m_target(nullptr)
@@ -54,6 +166,9 @@ QKeyframeAnimationPrivate::QKeyframeAnimationPrivate()
 
 }
 
+/*!
+    Constructs an QKeyframeAnimation with \a parent.
+*/
 QKeyframeAnimation::QKeyframeAnimation(QObject *parent)
     : QAbstractAnimation(*new QKeyframeAnimationPrivate(), parent)
 {
@@ -83,6 +198,9 @@ void QKeyframeAnimation::setFramePositions(const QVector<float> &positions)
     setDuration(d->m_maxposition);
 }
 
+/*!
+    Sets the \a keyframes of the animation. Old keyframes are cleared.
+ */
 void QKeyframeAnimation::setKeyframes(const QVector<Qt3DCore::QTransform *> &keyframes)
 {
     Q_D(QKeyframeAnimation);
@@ -181,6 +299,9 @@ QVector<float> QKeyframeAnimation::framePositions() const
     return d->m_framePositions;
 }
 
+/*!
+    Returns the list of keyframes.
+ */
 QVector<Qt3DCore::QTransform *> QKeyframeAnimation::keyframeList() const
 {
     Q_D(const QKeyframeAnimation);
@@ -251,12 +372,26 @@ void QKeyframeAnimation::setEndMode(QKeyframeAnimation::RepeatMode mode)
     }
 }
 
+/*!
+    Adds new \a keyframe at the end of the animation. The QTransform can
+    be added to the animation multiple times.
+ */
 void QKeyframeAnimation::addKeyframe(Qt3DCore::QTransform *keyframe)
 {
     Q_D(QKeyframeAnimation);
     d->m_keyframes.push_back(keyframe);
 }
 
+/*!
+    Removes a \a keyframe from the animation. If the same QTransform
+    is set as keyframe multiple times, all occurrences are removed.
+ */
+void QKeyframeAnimation::removeKeyframe(Qt3DCore::QTransform *keyframe)
+{
+    Q_D(QKeyframeAnimation);
+    d->m_keyframes.removeAll(keyframe);
+}
+
 QString QKeyframeAnimation::targetName() const
 {
     Q_D(const QKeyframeAnimation);
diff --git a/src/animation/frontend/qmorphinganimation.cpp b/src/animation/frontend/qmorphinganimation.cpp
index 4ee20f9cf..4191b9eab 100644
--- a/src/animation/frontend/qmorphinganimation.cpp
+++ b/src/animation/frontend/qmorphinganimation.cpp
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2016 The Qt Company Ltd.
+** Copyright (C) 2017 The Qt Company Ltd.
 ** Contact: http://www.qt.io/licensing/
 **
 ** This file is part of the Qt3D module of the Qt Toolkit.
@@ -41,6 +41,129 @@ QT_BEGIN_NAMESPACE
 
 namespace Qt3DAnimation {
 
+/*!
+    \class Qt3DAnimation::QMorphingAnimation
+    \brief A class implementing blend-shape morphing animation
+    \inmodule Qt3DAnimation
+    \since 5.9
+    \inherits Qt3DAnimation::QAbstractAnimation
+
+    A Qt3DAnimation::QMorphingAnimation class implements blend-shape morphing animation
+    to a target \l {Qt3DRender::QGeometryRenderer}{QGeometryRenderer}. The QMorphingAnimation
+    sets the correct \l {Qt3DRender::QAttribute}{QAttributes} from the
+    \l {Qt3DAnimation::QMorphTarget}{morph targets} to the target
+    \l {Qt3DRender::QGeometryRenderer::geometry} {QGeometryRenderer::geometry} and calculates
+    interpolator for the current position. The actual blending between the attributes must
+    be implemented in the material. Qt3DAnimation::QMorphPhongMaterial implements material
+    with morphing support for phong lighting model. The blending happens between
+    2 attributes - 'base' and 'target'. The names for the base and target attributes are taken from
+    the morph target names, where the base attribute retains the name it already has and the
+    target attribute name gets 'Target' appended to the name. The interpolator can be
+    set as a \l {Qt3DRender::QParameter}{QParameter} to the used material.
+    All morph targets in the animation should contain the attributes with same names as those
+    in the base geometry.
+
+*/
+/*!
+    \qmltype MorphingAnimation
+    \brief A type implementing blend-shape morphing animation
+    \inqmlmodule Qt3D.Animation
+    \since 5.9
+    \inherits AbstractAnimation
+    \instantiates Qt3DAnimation::QMorphingAnimation
+
+    A MorphingAnimation type implements blend-shape morphing animation
+    to a target \l GeometryRenderer. The MorphingAnimation sets the correct
+    \l {Attribute}{Attributes} from the morph targets to the target
+    \l {Qt3D.Render::GeometryRenderer::geometry}{GeometryRenderer::geometry} and calculates
+    interpolator for the current position. The actual blending between the attributes must
+    be implemented in the material. MorphPhongMaterial implements material
+    with morphing support for phong lighting model. The blending happens between
+    2 attributes - 'base' and 'target'. The names for the base and target attributes are taken from
+    the morph target names, where the base attribute retains the name it already has and the
+    target attribute name gets 'Target' appended to the name. All morph targets in the animation
+    should contain the attributes with same names as those in the base geometry.
+
+*/
+/*!
+    \property Qt3DAnimation::QMorphingAnimation::targetPositions
+    Holds the position values of the morph target. Each position in the list specifies the position
+    of the corresponding morph target with the same index. The values must be in an ascending order.
+    Values can be positive or negative and do not have any predefined unit.
+*/
+/*!
+    \property Qt3DAnimation::QMorphingAnimation::interpolator
+    Holds the interpolator between base and target attributes.
+    \readonly
+*/
+/*!
+    \property Qt3DAnimation::QMorphingAnimation::target
+    Holds the target QGeometryRenderer the morphing animation is applied to.
+*/
+/*!
+    \property Qt3DAnimation::QMorphingAnimation::targetName
+    Holds the name of the target geometry. This is a convenience property making it
+    easier to match the target geometry to the morphing animation. The name
+    is usually same as the name of the parent entity of the target QGeometryRenderer, but
+    does not have to be.
+*/
+/*!
+    \property Qt3DAnimation::QMorphingAnimation::method
+    Holds the morphing method. The default is Relative.
+*/
+/*!
+    \property Qt3DAnimation::QMorphingAnimation::easing
+    Holds the easing curve of the interpolator between morph targets.
+*/
+/*!
+    \enum Qt3DAnimation::QMorphingAnimation::Method
+
+    This enumeration specifies the morphing method.
+    \value Normalized The blending should use the normalized formula;
+                      V' = Vbase * (1.0 - sum(Wi)) + sum[Vi * Wi]
+    \value Relative The blending should use the relative formula;
+                      V' = Vbase + sum[Vi * Wi]
+*/
+
+/*!
+    \qmlproperty list<real> MorphingAnimation::targetPositions
+    Holds the position values of the morph target. Each position in the list specifies the position
+    of the corresponding morph target with the same index. The values must be in an ascending order.
+    Values can be positive or negative and do not have any predefined unit.
+*/
+/*!
+    \qmlproperty real MorphingAnimation::interpolator
+    Holds the interpolator between base and target attributes.
+    \readonly
+*/
+/*!
+    \qmlproperty GeometryRenderer MorphingAnimation::target
+    Holds the target GeometryRenderer the morphing animation is applied to.
+*/
+/*!
+    \qmlproperty string MorphingAnimation::targetName
+    Holds the name of the target geometry. This is a convenience property making it
+    easier to match the target geometry to the morphing animation. The name
+    is usually same as the name of the parent entity of the target GeometryRenderer, but
+    does not have to be.
+*/
+/*!
+    \qmlproperty enumeration MorphingAnimation::method
+    Holds the morphing method.  The default is Relative.
+    \list
+    \li Normalized
+    \li Relative
+    \endlist
+*/
+/*!
+    \qmlproperty EasingCurve MorphingAnimation::easing
+    Holds the easing curve of the interpolator between morph targets.
+*/
+/*!
+    \qmlproperty list<MorphTarget> MorphingAnimation::morphTargets
+    Holds the list of morph targets in the morphing animation.
+*/
+
 QMorphingAnimationPrivate::QMorphingAnimationPrivate()
     : QAbstractAnimationPrivate(QAbstractAnimation::MorphingAnimation)
     , m_minposition(0.0f)
@@ -148,6 +271,9 @@ void QMorphingAnimationPrivate::setTargetInterpolated(int morphTarget)
     m_currentTarget = target;
 }
 
+/*!
+    Construct a new QMorphingAnimation with \a parent.
+ */
 QMorphingAnimation::QMorphingAnimation(QObject *parent)
     : QAbstractAnimation(*new QMorphingAnimationPrivate, parent)
 {
@@ -192,6 +318,9 @@ QEasingCurve QMorphingAnimation::easing() const
     return d->m_easing;
 }
 
+/*!
+    Set morph \a targets to animation. Old targets are cleared.
+*/
 void QMorphingAnimation::setMorphTargets(const QVector<Qt3DAnimation::QMorphTarget *> &targets)
 {
     Q_D(QMorphingAnimation);
@@ -200,6 +329,9 @@ void QMorphingAnimation::setMorphTargets(const QVector<Qt3DAnimation::QMorphTarg
     d->m_position = -1.0f;
 }
 
+/*!
+    Add new morph \a target at the end of the animation.
+*/
 void QMorphingAnimation::addMorphTarget(Qt3DAnimation::QMorphTarget *target)
 {
     Q_D(QMorphingAnimation);
@@ -211,6 +343,9 @@ void QMorphingAnimation::addMorphTarget(Qt3DAnimation::QMorphTarget *target)
     }
 }
 
+/*!
+    Remove morph \a target from the animation.
+*/
 void QMorphingAnimation::removeMorphTarget(Qt3DAnimation::QMorphTarget *target)
 {
     Q_D(QMorphingAnimation);
@@ -246,6 +381,9 @@ void QMorphingAnimation::setTarget(Qt3DRender::QGeometryRenderer *target)
     }
 }
 
+/*!
+    Sets morph \a weights at \a positionIndex.
+*/
 void QMorphingAnimation::setWeights(int positionIndex, const QVector<float> &weights)
 {
     Q_D(QMorphingAnimation);
@@ -257,12 +395,18 @@ void QMorphingAnimation::setWeights(int positionIndex, const QVector<float> &wei
     d->m_position = -1.0f;
 }
 
+/*!
+    Return morph weights at \a positionIndex.
+*/
 QVector<float> QMorphingAnimation::getWeights(int positionIndex)
 {
     Q_D(QMorphingAnimation);
     return *d->m_weights[positionIndex];
 }
 
+/*!
+    Return morph target list.
+*/
 QVector<Qt3DAnimation::QMorphTarget *> QMorphingAnimation::morphTargetList()
 {
     Q_D(QMorphingAnimation);
diff --git a/src/animation/frontend/qmorphtarget.cpp b/src/animation/frontend/qmorphtarget.cpp
index 1040e33ff..e16dd8698 100644
--- a/src/animation/frontend/qmorphtarget.cpp
+++ b/src/animation/frontend/qmorphtarget.cpp
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2016 The Qt Company Ltd.
+** Copyright (C) 2017 The Qt Company Ltd.
 ** Contact: http://www.qt.io/licensing/
 **
 ** This file is part of the Qt3D module of the Qt Toolkit.
@@ -41,6 +41,55 @@ QT_BEGIN_NAMESPACE
 
 namespace Qt3DAnimation {
 
+/*!
+    \class Qt3DAnimation::QMorphTarget
+    \brief A class providing morph targets to blend-shape animation
+    \inmodule Qt3DAnimation
+    \since 5.9
+    \inherits QObject
+
+    A Qt3DAnimation::QMorphTarget class is a convenience class, which provides a list
+    of \l {Qt3DRender::QAttribute} {QAttributes}, which the QMorphingAnimation uses
+    to animate geometry. A QMorphTarget can also be created based on existing
+    \l Qt3DRender::QGeometry.
+
+*/
+/*!
+    \qmltype MorphTarget
+    \brief A type providing morph targets to blend-shape animation
+    \inqmlmodule Qt3D.Animation
+    \since 5.9
+    \inherits QtObject
+    \instantiates Qt3DAnimation::QMorphTarget
+
+    A MorphTarget type is a convenience type, which provides a list
+    of \l {Qt3D.Render::Attribute} {Attributes}, which the MorphingAnimation uses
+    to animate geometry. A MorphTarget can also be created based on existing
+    \l {Qt3D.Render::Geometry}{Geometry}.
+
+*/
+
+/*!
+    \property Qt3DAnimation::QMorphTarget::attributeNames
+    Holds a list of attribute names contained in the morph target.
+    \readonly
+*/
+
+/*!
+    \qmlproperty list<string> MorphTarget::attributeNames
+    Holds a list of attribute names contained in the morph target.
+    \readonly
+*/
+/*!
+    \qmlproperty list<Attribute> MorphTarget::attributes
+    Holds the list of attributes in the morph target.
+*/
+/*!
+    \qmlmethod MorphTarget Qt3D.Animation::MorphTarget::fromGeometry(geometry, stringList)
+    Returns a morph target based on the attributes defined by the given stringList from
+    the given geometry.
+*/
+
 QMorphTargetPrivate::QMorphTargetPrivate()
     : QObjectPrivate()
 {
@@ -54,12 +103,18 @@ void QMorphTargetPrivate::updateAttributeNames()
         m_attributeNames.push_back(attr->name());
 }
 
+/*!
+    Constructs a QMorphTarget with given \a parent.
+*/
 QMorphTarget::QMorphTarget(QObject *parent)
     : QObject(*new QMorphTargetPrivate, parent)
 {
 
 }
 
+/*!
+    Returns a list of attributes contained in the morph target.
+*/
 QVector<Qt3DRender::QAttribute *> QMorphTarget::attributeList() const
 {
     Q_D(const QMorphTarget);
@@ -72,6 +127,9 @@ QStringList QMorphTarget::attributeNames() const
     return d->m_attributeNames;
 }
 
+/*!
+    Sets \a attributes to the morph target. Old attributes are cleared.
+*/
 void QMorphTarget::setAttributes(const QVector<Qt3DRender::QAttribute *> &attributes)
 {
     Q_D(QMorphTarget);
@@ -83,6 +141,10 @@ void QMorphTarget::setAttributes(const QVector<Qt3DRender::QAttribute *> &attrib
     emit attributeNamesChanged(d->m_attributeNames);
 }
 
+/*!
+    Adds an \a attribute the morph target. An attribute with the same
+    name must not have been added previously to the morph target.
+*/
 void QMorphTarget::addAttribute(Qt3DRender::QAttribute *attribute)
 {
     Q_D(QMorphTarget);
@@ -95,6 +157,9 @@ void QMorphTarget::addAttribute(Qt3DRender::QAttribute *attribute)
     emit attributeNamesChanged(d->m_attributeNames);
 }
 
+/*!
+    Removes an \a attribute from the morph target.
+*/
 void QMorphTarget::removeAttribute(Qt3DRender::QAttribute *attribute)
 {
     Q_D(QMorphTarget);
@@ -105,6 +170,9 @@ void QMorphTarget::removeAttribute(Qt3DRender::QAttribute *attribute)
     }
 }
 
+/*!
+    Returns a morph target based on the \a attributes in the given \a geometry.
+*/
 QMorphTarget *QMorphTarget::fromGeometry(Qt3DRender::QGeometry *geometry, const QStringList &attributes)
 {
     QMorphTarget *target = new QMorphTarget();
diff --git a/src/animation/frontend/qvertexblendanimation.cpp b/src/animation/frontend/qvertexblendanimation.cpp
index 8eb0e5751..efc36e45c 100644
--- a/src/animation/frontend/qvertexblendanimation.cpp
+++ b/src/animation/frontend/qvertexblendanimation.cpp
@@ -42,6 +42,100 @@ QT_BEGIN_NAMESPACE
 
 namespace Qt3DAnimation {
 
+/*!
+    \class Qt3DAnimation::QVertexBlendAnimation
+    \brief A class implementing vertex-blend morphing animation
+    \inmodule Qt3DAnimation
+    \since 5.9
+    \inherits Qt3DAnimation::QAbstractAnimation
+
+    A Qt3DAnimation::QVertexBlendAnimation class implements vertex-blend morphing animation
+    to a target \l {Qt3DRender::QGeometryRenderer}{QGeometryRenderer}. The QVertexBlendAnimation
+    sets the correct \l {Qt3DRender::QAttribute}{QAttributes} from the
+    \l {Qt3DAnimation::QMorphTarget}{morph targets} to the target
+    \l {Qt3DRender::QGeometryRenderer::geometry} {QGeometryRenderer::geometry} and calculates
+    interpolator for the current position. Unlike with QMorphingAnimation, where the blending is
+    controller with blend weights, the blending occurs between sequential morph targets.
+    The actual blending between the attributes must be implemented in the material.
+    Qt3DAnimation::QMorphPhongMaterial implements material with morphing support for phong
+    lighting model. The blending happens between 2 attributes - 'base' and 'target'.
+    The names for the base and target attributes are taken from the morph target names,
+    where the base attribute retains the name it already has and the target attribute name
+    gets 'Target' appended to the name. The interpolator can be set as
+    a \l {Qt3DRender::QParameter}{QParameter} to the used material.
+    All morph targets in the animation should contain the attributes with same names as those
+    in the base geometry.
+
+*/
+/*!
+    \qmltype VertexBlendAnimation
+    \brief A type implementing vertex-blend morphing animation
+    \inqmlmodule Qt3D.Animation
+    \since 5.9
+    \inherits AbstractAnimation
+    \instantiates Qt3DAnimation::QVertexBlendAnimation
+
+    A VertexBlendAnimation type implements vertex-blend morphing animation
+    to a target \l GeometryRenderer. The VertexBlendAnimation sets the correct
+    \l {Attribute}{Attributes} from the morph targets to the target
+    \l {Qt3D.Render::GeometryRenderer::geometry}{GeometryRenderer::geometry} and calculates
+    interpolator for the current position. Unlike with MorphingAnimation, where the blending is
+    controller with blend weights, the blending occurs between sequential morph targets.
+    The actual blending between the attributes must be implemented in the material.
+    MorphPhongMaterial implements material with morphing support for phong lighting model.
+    The blending happens between 2 attributes - 'base' and 'target'. The names for the base
+    and target attributes are taken from the morph target names, where the base attribute
+    retains the name it already has and the target attribute name gets 'Target' appended to
+    the name. All morph targets in the animation should contain the attributes with same names
+    as those in the base geometry.
+
+*/
+/*!
+    \property Qt3DAnimation::QVertexBlendAnimation::targetPositions
+    Holds the position values of the morph target. Each position in the list specifies the position
+    of the corresponding morph target with the same index. The values must be in an ascending order.
+    Values can be positive or negative and do not have any predefined unit.
+*/
+/*!
+    \property Qt3DAnimation::QVertexBlendAnimation::interpolator
+    Holds the interpolator between base and target attributes.
+    \readonly
+*/
+/*!
+    \property Qt3DAnimation::QVertexBlendAnimation::target
+    Holds the target QGeometryRenderer the morphing animation is applied to.
+*/
+/*!
+    \property Qt3DAnimation::QVertexBlendAnimation::targetName
+    Holds the name of the target geometry. This is a convenience property making it
+    easier to match the target geometry to the morphing animation. The name
+    is usually same as the name of the parent entity of the target QGeometryRenderer, but
+    does not have to be.
+*/
+
+/*!
+    \qmlproperty list<real> VertexBlendAnimation::targetPositions
+    Holds the position values of the morph target. Each position in the list specifies the position
+    of the corresponding morph target with the same index. The values must be in an ascending order.
+    Values can be positive or negative and do not have any predefined unit.
+*/
+/*!
+    \qmlproperty real VertexBlendAnimation::interpolator
+    Holds the interpolator between base and target attributes.
+    \readonly
+*/
+/*!
+    \qmlproperty VertexBlendAnimation::target
+    Holds the target GeometryRenderer the morphing animation is applied to.
+*/
+/*!
+    \qmlproperty string VertexBlendAnimation::targetName
+    Holds the name of the target geometry. This is a convenience property making it
+    easier to match the target geometry to the morphing animation. The name
+    is usually same as the name of the parent entity of the target GeometryRenderer, but
+    does not have to be.
+*/
+
 QVertexBlendAnimationPrivate::QVertexBlendAnimationPrivate()
     : QAbstractAnimationPrivate(QAbstractAnimation::VertexBlendAnimation)
     , m_interpolator(0.0f)
@@ -130,6 +224,9 @@ void QVertexBlendAnimationPrivate::updateAnimation(float position)
     }
 }
 
+/*!
+    Construct a new QVertexBlendAnimation with \a parent.
+ */
 QVertexBlendAnimation::QVertexBlendAnimation(QObject *parent)
     : QAbstractAnimation(*new QVertexBlendAnimationPrivate, parent)
 {
@@ -162,12 +259,18 @@ QString QVertexBlendAnimation::targetName() const
     return d->m_targetName;
 }
 
+/*!
+    Set morph \a targets to animation. Old targets are cleared.
+*/
 void QVertexBlendAnimation::setMorphTargets(const QVector<Qt3DAnimation::QMorphTarget *> &targets)
 {
     Q_D(QVertexBlendAnimation);
     d->m_morphTargets = targets;
 }
 
+/*!
+    Add new morph \a target at the end of the animation.
+*/
 void QVertexBlendAnimation::addMorphTarget(Qt3DAnimation::QMorphTarget *target)
 {
     Q_D(QVertexBlendAnimation);
@@ -175,6 +278,9 @@ void QVertexBlendAnimation::addMorphTarget(Qt3DAnimation::QMorphTarget *target)
         d->m_morphTargets.push_back(target);
 }
 
+/*!
+    Remove morph \a target from the animation.
+*/
 void QVertexBlendAnimation::removeMorphTarget(Qt3DAnimation::QMorphTarget *target)
 {
     Q_D(QVertexBlendAnimation);
@@ -200,6 +306,9 @@ void QVertexBlendAnimation::setTarget(Qt3DRender::QGeometryRenderer *target)
     }
 }
 
+/*!
+    Return morph target list.
+*/
 QVector<Qt3DAnimation::QMorphTarget *> QVertexBlendAnimation::morphTargetList()
 {
     Q_D(QVertexBlendAnimation);