diff --git a/animations/animation.cpp b/animations/animation.cpp
index 7c8499a79..a593d58df 100644
--- a/animations/animation.cpp
+++ b/animations/animation.cpp
@@ -59,9 +59,9 @@ void Animation::setDuration(int duration)
     d->duration = qMax(0, duration);
 }
 
-void Animation::setWidgetToAnimate(QGraphicsWidget* receiver)
+void Animation::setWidgetToAnimate(QGraphicsWidget* widget)
 {
-    d->animObject = receiver;
+    d->animObject = widget;
 }
 
 QGraphicsWidget* Animation::widgetToAnimate()
diff --git a/animations/animation.h b/animations/animation.h
index ee79dcf65..00cfd1504 100644
--- a/animations/animation.h
+++ b/animations/animation.h
@@ -52,12 +52,14 @@ class PLASMA_EXPORT Animation : public QAbstractAnimation
 
 public:
     /**
-     * Get the animation duration.
+     * Get the animation duration. It can be set using the property duration.
      * @return duration in ms.
      */
     int duration() const;
 
-    /* FIXME: find a better place and name for it. */
+    /**
+     * Animation movement reference (used by \ref RotationAnimation).
+     */
     enum Reference{
         Center,
         Up,
@@ -66,14 +68,29 @@ public:
         Right
     };
 
+    /**
+     * Default constructor.
+     *
+     * @param parent Object parent (might be set when using
+     * \ref Animator::create factory).
+     *
+     */
     explicit Animation(QObject* parent = 0);
+
+    /**
+     * Destructor.
+     */
     virtual ~Animation() = 0;
 
     /**
      * Set the widget on which the animation is to be performed.
+     *
+     * If the animation class has any special initialization to be done
+     * in the target widget, you should reimplement this method in
+     * the derived class.
      * @arg receiver The QGraphicsWidget to be animated.
      */
-    virtual void setWidgetToAnimate(QGraphicsWidget* receiver);
+    virtual void setWidgetToAnimate(QGraphicsWidget* widget);
 
     /**
      * The widget that the animation will be performed upon
@@ -93,16 +110,36 @@ public:
 protected:
 
     /**
-     * Change the animation duration. Default is 1000ms.
+     * Change the animation duration. Default is 250ms.
      * @arg duration The new duration of the animation.
      */
     virtual void setDuration(int duration = 250);
 
+    /**
+     * QAbstractAnimation will call this method while the animation
+     * is running. Each specialized animation class should implement
+     * the correct behavior for it.
+     * @param currentTime Slapsed time using the \ref duration as reference
+     * (it will be from duration up to zero if the animation is running
+     * backwards).
+     */
     virtual void updateCurrentTime(int currentTime);
 
+    /**
+     * Internal use only, access the easing curve object (see
+     * \ref AnimationPrivate). Commonly used if a non-linear
+     * animation is desired while setting the delta in \ref updateCurrentTime.
+     *
+     * @return An internal easing curve (default is Type::Linear).
+     */
     QEasingCurve &easingCurve();
 
 private:
+
+    /**
+     * Internal pimple (actually is used as a data structure, see
+     * \ref AnimationPrivate).
+     */
     AnimationPrivate *const d;
 
 };
diff --git a/animations/fade_p.h b/animations/fade_p.h
index 67837b043..a505cc741 100644
--- a/animations/fade_p.h
+++ b/animations/fade_p.h
@@ -34,7 +34,9 @@ namespace Plasma
  * @class Fade plasma/animations/fade.h
  * @short Fade effect
  *
- * Effect that slowly transforms the opacity of the object to the given value.
+ * Effect that slowly transforms the opacity of the object from a starting
+ * value to a target value. The range is 0 (full translucent) to 1 (full
+ * opaque).
  */
 class FadeAnimation : public Animation
 {
@@ -43,15 +45,50 @@ class FadeAnimation : public Animation
     Q_PROPERTY(qreal targetOpacity READ targetOpacity WRITE setTargetOpacity)
 
 public:
+    /** Default constructor */
     FadeAnimation(QObject *parent = 0);
+    /** Destructor */
     virtual ~FadeAnimation();
 
+    /**
+     * Access start opacity of the target widget.
+     *
+     * You can set both a start and an end opacity for an widget when
+     * using this animation class. See \ref setStartOpacity.
+     * @return The opacity (range is 0 to 1).
+     */
     qreal startOpacity() const;
+    /**
+     * Set the start opacity of the target widget.
+     *
+     * See also \ref targetOpacity.
+     * @param qreal The opacity (range is 0 to 1).
+     */
     void setStartOpacity(qreal);
 
+    /**
+     * Access final opacity of the target widget.
+     *
+     * You can set both a start and an end opacity for an widget when
+     * using this animation class. See \ref setTargetOpacity.
+     * @return The opacity (range is 0 to 1).
+     */
     qreal targetOpacity() const;
+    /**
+     * Set the final opacity of the target widget.
+     *
+     * See also \ref startOpacity.
+     * @param qreal The opacity (range is 0 to 1).
+     */
     void setTargetOpacity(qreal);
 
+    /**
+     * Set the widget on which the animation is to be performed.
+     *
+     * This animation reimplements it to make possible to apply the
+     * start opacity in the widget (see \ref setStartOpacity).
+     * @arg receiver The QGraphicsWidget to be animated.
+     */
     void setWidgetToAnimate(QGraphicsWidget *widget);
 
 protected:
@@ -59,7 +96,9 @@ protected:
     void updateCurrentTime(int currentTime);
 
 private:
+    /** Initial opacity */
     qreal m_startOpacity;
+    /** Final opacity */
     qreal m_targetOpacity;
 };