Update Animation's public header comments 55/58555/3
authorSeoyeon Kim <seoyeon2.kim@samsung.com>
Tue, 2 Feb 2016 01:33:32 +0000 (10:33 +0900)
committerSeoyeon Kim <seoyeon2.kim@samsung.com>
Wed, 3 Feb 2016 10:31:08 +0000 (19:31 +0900)
Change-Id: I7997fdce2be6deda51f49742264a308555566873

dali/public-api/animation/alpha-function.h
dali/public-api/animation/animation.h
dali/public-api/animation/constraint-source.h
dali/public-api/animation/constraint.h
dali/public-api/animation/constraints.h
dali/public-api/animation/key-frames.h
dali/public-api/animation/linear-constrainer.h
dali/public-api/animation/path.h

index f0af62e..97ec864 100644 (file)
@@ -35,10 +35,12 @@ namespace Dali
 
 typedef float (*AlphaFunctionPrototype)(float progress); ///< Prototype of an alpha function @SINCE_1_0.0
 
-  /*
+  /**
    * @brief Alpha functions are used in animations to specify the rate of change of the animation parameter over time.
+   *
    * Understanding an animation as a parametric function over time, the alpha function is applied to the parameter of
    * the animation before computing the final animation value.
+   * @SINCE_1_0.0
    */
 class DALI_IMPORT_API AlphaFunction
 {
@@ -78,9 +80,9 @@ public:
    */
   enum Mode
   {
-    BUILTIN_FUNCTION,  //< The user has specified a built-in function
-    CUSTOM_FUNCTION,   //< The user has provided a custom function
-    BEZIER             //< The user has provided the control points of a bezier curve
+    BUILTIN_FUNCTION,  ///< The user has specified a built-in function @SINCE_1_0.0
+    CUSTOM_FUNCTION,   ///< The user has provided a custom function @SINCE_1_0.0
+    BEZIER             ///< The user has provided the control points of a bezier curve @SINCE_1_0.0
   };
 
   /**
@@ -113,6 +115,7 @@ public:
 
   /**
    * @brief Constructor.
+   *
    * Creates a bezier alpha function. The bezier will have the first point at (0,0) and
    * the end point at (1,1).
    * @SINCE_1_0.0
@@ -140,10 +143,10 @@ public:
   AlphaFunctionPrototype GetCustomFunction() const;
 
   /**
-   * @brief Returns the built0in function used by the alpha function
+   * @brief Returns the built-in function used by the alpha function
    * @SINCE_1_0.0
    * @return One of the built-in alpha functions. In case no built-in function
-   * has been specified, it will return AlphaFunction::DEfAULT
+   * has been specified, it will return AlphaFunction::DEFAULT
    */
   BuiltinFunction GetBuiltinFunction() const;
 
index d562c63..9f31050 100644 (file)
@@ -142,7 +142,7 @@ public:
   /**
    * @brief Create an uninitialized Animation; this can be initialized with Animation::New().
    *
-   * Calling member functions with an uninitialized Dali::Object is not allowed.
+   * Calling member functions with an uninitialized Animation handle is not allowed.
    * @SINCE_1_0.0
    */
   Animation();
@@ -156,19 +156,19 @@ public:
    * @SINCE_1_0.0
    * @param [in] durationSeconds The duration in seconds.
    * @return A handle to a newly allocated Dali resource.
-   * @pre durationSeconds must be greater than zero.
+   * @pre DurationSeconds must be greater than zero.
    */
   static Animation New(float durationSeconds);
 
   /**
-   * @brief Downcast an Object handle to Animation.
+   * @brief Downcast a handle to Animation handle.
    *
    * If handle points to an Animation object the downcast produces
    * valid handle. If not the returned handle is left uninitialized.
    *
    * @SINCE_1_0.0
-   * @param[in] handle to An object
-   * @return handle to a Animation object or an uninitialized handle
+   * @param[in] handle Handle to an object
+   * @return Handle to a Animation object or an uninitialized handle
    */
   static Animation DownCast( BaseHandle handle );
 
@@ -202,7 +202,7 @@ public:
    *
    * @SINCE_1_0.0
    * @param[in] seconds The duration in seconds.
-   * @pre durationSeconds must be greater than zero.
+   * @pre DurationSeconds must be greater than zero.
    */
   void SetDuration(float seconds);
 
@@ -215,13 +215,13 @@ public:
   float GetDuration() const;
 
   /**
-   * @brief Set whether the animation will loop forever.
+   * @brief Set whether the animation will loop.
    *
    * This function resets the loop count and should not be used with SetLoopCount(int).
    * Setting this parameter does not cause the animation to Play()
    *
    * @SINCE_1_0.0
-   * @param[in] looping If true then the animation will loop forever, if false it will never loop.
+   * @param[in] looping True if the animation will loop.
    */
   void SetLooping(bool looping);
 
@@ -322,12 +322,11 @@ public:
   /*
    * @brief Sets the progress of the animation.
    *
-   * When played, the animation will start from this point.
-   * If playing, the animation will jump to, and continue playing from this point.
-   *
-   * The progress must be in the 0-1 interval or in the play range interval
-   * if defined ( See SetPlayRange ), otherwise, it will be ignored.
+   * The animation will play (or continue playing) from this point. The progress
+   * must be in the 0-1 interval or in the play range interval if defined ( See @ref Animation::SetPlayRange ),
+   * otherwise, it will be ignored.
    *
+   * @SINCE_1_0.0
    * @param[in] progress The new progress as a normalized value between [0,1]
    * or between the play range if specified.
    */
@@ -357,12 +356,13 @@ public:
    * @brief Retrieve the speed factor of the animation
    *
    * @SINCE_1_0.0
-   * @return speed factor
+   * @return Speed factor
    */
   float GetSpeedFactor() const;
 
   /**
    * @brief Set the playing range.
+   *
    * Animation will play between the values specified. Both values ( range.x and range.y ) should be between 0-1,
    * otherwise they will be ignored. If the range provided is not in proper order ( minimum,maximum ), it will be reordered.
    *
@@ -388,7 +388,8 @@ public:
 
   /**
    * @brief Play the animation from a given point.
-   * The progress must be in the 0-1 interval or in the play range interval if defined ( See SetPlayRange ),
+   *
+   * The progress must be in the 0-1 interval or in the play range interval if defined ( See @ref Animation::SetPlayRange ),
    * otherwise, it will be ignored.
    *
    * @SINCE_1_0.0
@@ -420,7 +421,7 @@ public:
    * @brief Connect to this signal to be notified when an Animation's animations have finished.
    *
    * @SINCE_1_0.0
-   * @return A signal object to Connect() with.
+   * @return A signal object to @ref Signal::Connect() with.
    */
   AnimationSignalType& FinishedSignal();
 
@@ -516,8 +517,8 @@ public:
    * @brief Animate a property between keyframes.
    *
    * @SINCE_1_0.0
-   * @param [in] target The target object/property to animate.
-   * @param [in] keyFrames The key frames
+   * @param [in] target The target object property to animate.
+   * @param [in] keyFrames The set of time/value pairs between which to animate.
    */
   void AnimateBetween(Property target, KeyFrames& keyFrames);
 
@@ -525,8 +526,8 @@ public:
    * @brief Animate a property between keyframes.
    *
    * @SINCE_1_0.0
-   * @param [in] target The target object property to animate
-   * @param [in] keyFrames The set of time / value pairs between which to animate.
+   * @param [in] target The target object property to animate
+   * @param [in] keyFrames The set of time/value pairs between which to animate.
    * @param [in] interpolation The method used to interpolate between values.
    */
   void AnimateBetween(Property target, KeyFrames& keyFrames, Interpolation interpolation);
@@ -535,8 +536,8 @@ public:
    * @brief Animate a property between keyframes.
    *
    * @SINCE_1_0.0
-   * @param [in] target The target object/property to animate.
-   * @param [in] keyFrames The key frames
+   * @param [in] target The target object property to animate.
+   * @param [in] keyFrames The set of time/value pairs between which to animate.
    * @param [in] alpha The alpha function to apply.
    */
   void AnimateBetween(Property target, KeyFrames& keyFrames, AlphaFunction alpha);
@@ -545,8 +546,8 @@ public:
    * @brief Animate a property between keyframes.
    *
    * @SINCE_1_0.0
-   * @param [in] target The target object property to animate
-   * @param [in] keyFrames The set of time / value pairs between which to animate.
+   * @param [in] target The target object property to animate
+   * @param [in] keyFrames The set of time/value pairs between which to animate.
    * @param [in] alpha The alpha function to apply.
    * @param [in] interpolation The method used to interpolate between values.
    */
@@ -556,8 +557,8 @@ public:
    * @brief Animate a property between keyframes.
    *
    * @SINCE_1_0.0
-   * @param [in] target The target object/property to animate.
-   * @param [in] keyFrames The key frames
+   * @param [in] target The target object property to animate.
+   * @param [in] keyFrames The set of time/value pairs between which to animate.
    * @param [in] period The effect will occur during this time period.
    */
   void AnimateBetween(Property target, KeyFrames& keyFrames, TimePeriod period);
@@ -566,8 +567,8 @@ public:
    * @brief Animate a property between keyframes.
    *
    * @SINCE_1_0.0
-   * @param [in] target The target object property to animate
-   * @param [in] keyFrames The set of time / value pairs between which to animate.
+   * @param [in] target The target object property to animate
+   * @param [in] keyFrames The set of time/value pairs between which to animate.
    * @param [in] period The effect will occur duing this time period.
    * @param [in] interpolation The method used to interpolate between values.
    */
@@ -577,8 +578,8 @@ public:
    * @brief Animate a property between keyframes.
    *
    * @SINCE_1_0.0
-   * @param [in] target The target object/property to animate.
-   * @param [in] keyFrames The key frames
+   * @param [in] target The target object property to animate.
+   * @param [in] keyFrames The set of time/value pairs between which to animate.
    * @param [in] alpha The alpha function to apply.
    * @param [in] period The effect will occur during this time period.
    */
@@ -588,8 +589,8 @@ public:
    * @brief Animate a property between keyframes.
    *
    * @SINCE_1_0.0
-   * @param [in] target The target object property to animate
-   * @param [in] keyFrames The set of time / value pairs between which to animate.
+   * @param [in] target The target object property to animate
+   * @param [in] keyFrames The set of time/value pairs between which to animate.
    * @param [in] alpha The alpha function to apply to the overall progress.
    * @param [in] period The effect will occur duing this time period.
    * @param [in] interpolation The method used to interpolate between values.
@@ -600,7 +601,9 @@ public:
   // Actor-specific convenience methods
 
   /**
-   * @brief Animate an actor's position and orientation through a predefined path. The actor will rotate to orient the supplied
+   * @brief Animate an actor's position and orientation through a predefined path.
+   *
+   * The actor will rotate to orient the supplied
    * forward vector with the path's tangent. If forward is the zero vector then no rotation will happen.
    *
    * @SINCE_1_0.0
@@ -611,7 +614,9 @@ public:
   void Animate( Actor actor, Path path, const Vector3& forward );
 
   /**
-   * @brief Animate an actor's position and orientation through a predefined path. The actor will rotate to orient the supplied
+   * @brief Animate an actor's position and orientation through a predefined path.
+   *
+   * The actor will rotate to orient the supplied
    * forward vector with the path's tangent. If forward is the zero vector then no rotation will happen.
    *
    * @SINCE_1_0.0
@@ -623,7 +628,9 @@ public:
   void Animate( Actor actor, Path path, const Vector3& forward, AlphaFunction alpha );
 
   /**
-   * @brief Animate an actor's position and orientation through a predefined path. The actor will rotate to orient the supplied
+   * @brief Animate an actor's position and orientation through a predefined path.
+   *
+   * The actor will rotate to orient the supplied
    * forward vector with the path's tangent. If forward is the zero vector then no rotation will happen.
    *
    * @SINCE_1_0.0
@@ -635,7 +642,9 @@ public:
   void Animate( Actor actor, Path path, const Vector3& forward, TimePeriod period );
 
   /**
-   * @brief Animate an actor's position and orientation through a predefined path. The actor will rotate to orient the supplied
+   * @brief Animate an actor's position and orientation through a predefined path.
+   *
+   * The actor will rotate to orient the supplied
    * forward vector with the path's tangent. If forward is the zero vector then no rotation will happen.
    *
    * @SINCE_1_0.0
@@ -668,7 +677,7 @@ public:
 public: // Not intended for use by Application developers
 
   /**
-   * @brief This constructor is used by Dali New() methods
+   * @brief This constructor is used by Animation::New() methods
    * @SINCE_1_0.0
    * @param [in] animation A pointer to a newly allocated Dali resource
    */
index d04bd05..a3d5850 100644 (file)
@@ -67,7 +67,7 @@ struct DALI_IMPORT_API LocalSource
 struct DALI_IMPORT_API ParentSource
 {
   /**
-   * @brief Create a local constraint source.
+   * @brief Create a parent constraint source.
    *
    * @SINCE_1_0.0
    * @param [in] index The index of a property, provided by the parent of the constrained object.
index 6943dc4..1bf916a 100644 (file)
@@ -292,7 +292,7 @@ public:
   /**
    * @brief Create an uninitialized Constraint; this can be initialized with Constraint::New().
    *
-   * Calling member functions with an uninitialized Dali::Object is not allowed.
+   * Calling member functions with an uninitialized Constraint handle is not allowed.
    * @SINCE_1_0.0
    */
   Constraint();
@@ -306,6 +306,7 @@ public:
    * @endcode
    *
    * Create the constraint with this function as follows:
+   *
    * @code
    *   Constraint constraint = Constraint::New< Vector3 >( handle, CONSTRAINING_PROPERTY_INDEX, &MyFunction );
    * @endcode
@@ -337,6 +338,7 @@ public:
    * @endcode
    *
    * Create the constraint with this object as follows:
+   *
    * @code
    *   Constraint constraint = Constraint::New< Vector3 >( handle, CONSTRAINING_PROPERTY_INDEX, MyObject() );
    * @endcode
@@ -369,6 +371,7 @@ public:
    * @endcode
    *
    * Create the constraint with this object as follows:
+   *
    * @code
    *   Constraint constraint = Constraint::New< Vector3 >( handle, CONSTRAINING_PROPERTY_INDEX, MyObject(), &MyObject::MyMethod );
    * @endcode
@@ -426,13 +429,13 @@ public:
   Constraint& operator=( const Constraint& rhs );
 
   /**
-   * @brief Downcast an Object handle to Constraint handle.
+   * @brief Downcast a handle to Constraint handle.
    *
    * If handle points to a Constraint object the
    * downcast produces valid handle. If not the returned handle is left uninitialized.
    * @SINCE_1_0.0
-   * @param[in]  baseHandle  to An object
-   * @return handle to a Constraint object or an uninitialized handle
+   * @param[in] baseHandle BaseHandle to an object
+   * @return Handle to a Constraint object or an uninitialized handle
    */
   static Constraint DownCast( BaseHandle baseHandle );
 
@@ -477,9 +480,9 @@ public:
   Dali::Property::Index GetTargetProperty();
 
   /**
-   * @brief Set whether the constraint will "bake" a value when fully-applied.
+   * @brief Set the remove action. Constraint::Bake will "bake" a value when fully-applied.
    *
-   * Otherwise the constrained value will be discarded, when the constraint is removed.
+   * In case of Constraint::Discard, the constrained value will be discarded, when the constraint is removed.
    * The default value is Constraint::Bake.
    * @SINCE_1_0.0
    * @param[in] action The remove-action.
@@ -487,11 +490,10 @@ public:
   void SetRemoveAction( RemoveAction action );
 
   /**
-   * @brief Query whether the constraint will "bake" a value when fully-applied.
+   * @brief Retrieve the remove action that will happen when the constraint is removed.
    *
-   * Otherwise the constrained value will be discarded, when the constraint is removed.
    * @SINCE_1_0.0
-   * @return The apply-action.
+   * @return The remove-action.
    */
   RemoveAction GetRemoveAction() const;
 
@@ -514,7 +516,7 @@ public:
 public: // Not intended for use by Application developers
 
   /**
-   * @brief This constructor is used by Dali New() methods
+   * @brief This constructor is used by Constraint::New() methods
    * @SINCE_1_0.0
    * @param [in] constraint A pointer to a newly allocated Dali resource
    */
index 749548b..150d8f6 100644 (file)
@@ -35,9 +35,10 @@ namespace Dali
  */
 
 /**
- * @brief EqualToConstraint
+ * @brief The constraint function that updates the target property with the value of the first source.
  *
- * f(current, property) = property
+ * @e current = <em>input[0]</em>. @e current and <em>input[0]</em> indicate the target property
+ * and the first constraint source (the one added by the first Constraint::AddSource call), respectively.
  * @SINCE_1_0.0
  */
 struct EqualToConstraint
@@ -50,12 +51,11 @@ struct EqualToConstraint
   { }
 
   /**
-   * @brief override functor for float properties
+   * @brief Override functor for float properties
    *
    * @SINCE_1_0.0
    * @param[in, out] current The current property value, the constrained value is set
    * @param[in] inputs Contains the property to copy
-   * @return The copy of the input property
    */
   void operator()( float& current, const PropertyInputContainer& inputs )
   {
@@ -63,12 +63,11 @@ struct EqualToConstraint
   }
 
   /**
-   * @brief override functor for float properties
+   * @brief Override functor for Vector2 properties
    *
    * @SINCE_1_0.0
-   * @param[in] current The current property value, the constrained value is set
+   * @param[in, out] current The current property value, the constrained value is set
    * @param[in] inputs Contains the property to copy
-   * @return The copy of the input property
    */
   void operator()( Vector2& current, const PropertyInputContainer& inputs )
   {
@@ -76,12 +75,11 @@ struct EqualToConstraint
   }
 
   /**
-   * @brief override functor for float properties
+   * @brief Override functor for Vector3 properties
    *
    * @SINCE_1_0.0
    * @param[in,out] current The current property value, the constrained value is set
    * @param[in] inputs Contains the property to copy
-   * @return The copy of the input property
    */
   void operator()( Vector3& current, const PropertyInputContainer& inputs )
   {
@@ -89,12 +87,11 @@ struct EqualToConstraint
   }
 
   /**
-   * @brief override functor for float properties
+   * @brief Override functor for Vector4 properties
    *
    * @SINCE_1_0.0
    * @param[in,out] current The current property value, the constrained value is set
    * @param[in] inputs Contains the property to copy
-   * @return The copy of the input property
    */
   void operator()( Vector4& current, const PropertyInputContainer& inputs )
   {
@@ -102,12 +99,11 @@ struct EqualToConstraint
   }
 
   /**
-   * @brief override functor for float properties
+   * @brief Override functor for Quaternion properties
    *
    * @SINCE_1_0.0
    * @param[in,out] current The current property value, the constrained value is set
    * @param[in] inputs Contains the property to copy
-   * @return The copy of the input property
    */
   void operator()( Quaternion& current, const PropertyInputContainer& inputs )
   {
@@ -115,12 +111,11 @@ struct EqualToConstraint
   }
 
   /**
-   * @brief override functor for float properties
+   * @brief Override functor for Matrix3 properties
    *
    * @SINCE_1_0.0
    * @param[in,out] current The current property value
    * @param[in] inputs Contains the property to copy
-   * @return The copy of the input property
    */
   void operator()( Matrix3& current, const PropertyInputContainer& inputs )
   {
@@ -128,12 +123,11 @@ struct EqualToConstraint
   }
 
   /**
-   * @brief override functor for float properties
+   * @brief Override functor for Matrix properties
    *
    * @SINCE_1_0.0
    * @param[in,out] current The current property value, the constrained value is set
    * @param[in] inputs Contains the property to copy
-   * @return The copy of the input property
    */
   void operator()( Matrix& current, const PropertyInputContainer& inputs )
   {
@@ -143,9 +137,12 @@ struct EqualToConstraint
 };
 
 /**
- * @brief RelativeToConstraint for Vector3 properties
+ * @brief The constraint function that updates the target property with the value of the first source
+ * multiplied by scale parameter (for Vector3 properties).
  *
- * current = property * scale
+ * @e current = <em>input[0]</em> * @e scale. @e current, <em>input[0]</em>, and @e scale
+ * indicate the target property, the first constraint source, and the scale parameter, respectively.
+ * * implies element-wise multiplication.
  * @SINCE_1_0.0
  */
 struct RelativeToConstraint
@@ -153,6 +150,7 @@ struct RelativeToConstraint
   /**
    * @brief Constructor.
    * @SINCE_1_0.0
+   * @param[in] scale Scale factor
    */
   RelativeToConstraint( float scale )
   : mScale( scale, scale, scale ) { }
@@ -160,6 +158,7 @@ struct RelativeToConstraint
   /**
    * @brief Constructor.
    * @SINCE_1_0.0
+   * @param[in] scale Scale factor
    */
   RelativeToConstraint( const Vector3& scale )
   : mScale( scale ) { }
@@ -167,6 +166,8 @@ struct RelativeToConstraint
   /**
    * @brief Functor.
    * @SINCE_1_0.0
+   * @param[in,out] current The current property value (vector3 property * scale factor).
+   * @param[in] input Property container for current property calculation
    */
   void operator()( Vector3& current, const PropertyInputContainer& inputs )
   {
@@ -177,7 +178,11 @@ struct RelativeToConstraint
 };
 
 /**
- * @brief RelativeToConstraint for float properties
+ * @brief The constraint function that updates the target property with the value of the first source
+ * multiplied by scale parameter (for float properties).
+ *
+ * @e current = <em>input[0]</em> * @e scale. @e current, <em>input[0]</em>, and @e scale
+ * indicate the target property, the first constraint source, and the scale parameter, respectively.
  * @SINCE_1_0.0
  */
 struct RelativeToConstraintFloat
@@ -185,6 +190,7 @@ struct RelativeToConstraintFloat
   /**
    * @brief Constructor.
    * @SINCE_1_0.0
+   * @param[in] scale Scale factor
    */
   RelativeToConstraintFloat( float scale )
   : mScale( scale ) { }
@@ -192,6 +198,8 @@ struct RelativeToConstraintFloat
   /**
    * @brief Functor.
    * @SINCE_1_0.0
+   * @param[in,out] current The current property value (float property * scale factor).
+   * @param[in] input Property container for current property calculation
    */
   void operator()( float& current, const PropertyInputContainer& inputs )
   {
@@ -211,10 +219,9 @@ struct RelativeToConstraintFloat
  *
  * @SINCE_1_0.0
  * @param[in,out] current The current orientation property value, the constrained value is set.
- * @param[in] inputs Contains the World position of the target, the World position of the camera, and the world orientation of the target
- * @return The orientation of the camera
+ * @param[in] inputs Contains the world position of the target, the world position of the camera, and the world orientation of the target
  */
-inline void LookAt( Quaternion& current, const PropertyInputContainer& inputs )
+inline void LookAt( Dali::Quaternion& current, const Dali::PropertyInputContainer& inputs )
 {
   const PropertyInput& targetPosition( *inputs[0] );
   const PropertyInput& cameraPosition( *inputs[1] );
index 67a1e2a..c688e05 100644 (file)
@@ -49,29 +49,29 @@ class DALI_IMPORT_API KeyFrames : public BaseHandle
 {
 public:
   /**
-   * @brief Create an initialized KeyFrame handle.
+   * @brief Create an initialized KeyFrames handle.
    *
    * @SINCE_1_0.0
-   * @return a handle to a newly allocated Dali resource.
+   * @return A handle to a newly allocated Dali resource.
    */
   static KeyFrames New();
 
   /**
-   * @brief Downcast an Object handle to KeyFrames handle.
+   * @brief Downcast a handle to KeyFrames handle.
    *
    * If handle points to a KeyFrames object the downcast produces
    * valid handle. If not the returned handle is left uninitialized.
    * @SINCE_1_0.0
-   * @param[in] handle to An object
-   * @return handle to a KeyFrames object or an uninitialized handle
+   * @param[in] handle Handle to an object
+   * @return Handle to a KeyFrames object or an uninitialized handle
    */
   static KeyFrames DownCast( BaseHandle handle );
 
   /**
    * @brief Create an uninitialized KeyFrame handle.
    *
-   * This can be initialized with KeyFrame::New(). Calling member
-   * functions with an uninitialized Dali::Object is not allowed.
+   * This can be initialized with KeyFrame::New().
+   * Calling member functions with an uninitialized KeyFrames handle is not allowed.
    * @SINCE_1_0.0
    */
   KeyFrames();
@@ -115,7 +115,7 @@ public:
    *
    * The key frames should be added in time order.
    * @SINCE_1_0.0
-   * @param[in] progress A value between 0.0 and 1.0.
+   * @param[in] progress A progress value between 0.0 and 1.0.
    * @param[in] value A value.
    */
   void Add(float progress, Property::Value value);
@@ -125,7 +125,7 @@ public:
    *
    * The key frames should be added in time order.
    * @SINCE_1_0.0
-   * @param[in] progress A value between 0.0 and 1.0.
+   * @param[in] progress A progress value between 0.0 and 1.0.
    * @param[in] value A value.
    * @param[in] alpha The alpha function used to blend to the next keyframe
    */
@@ -134,7 +134,7 @@ public:
 
 public: // Not intended for application developers
   /**
-   * @brief This constructor is used by Dali::New() methods.
+   * @brief This constructor is used by KeyFrames::New() methods.
    *
    * @SINCE_1_0.0
    * @param[in] keyFrames A pointer to an internal KeyFrame resource
index 99a9936..173f839 100644 (file)
@@ -38,12 +38,20 @@ namespace Internal DALI_INTERNAL
 }
 
 /**
- * @brief
+ * @brief LinearConstrainer applies constraints to objects given a linear map.
  *
- * LinearConstrainer applies constraints to objects given a linear map.
  * A linear map is defined by a set of value-progress pairs.
  * Progress must be normalized between [0,1]. If no progress is defined, the values
  * are considered to be equally spaced along the x axis.
+ *
+ * Basically, a linear constrainer allows constraining a property to another property
+ * with the changes mapped over a certain range. For example, if you want to change the
+ * opacity of an actor depending on its position along the X-axis, so that it’s fully
+ * transparent on the edges and fully opaque in the center. To do this, an array with
+ * values, 0.0f, 1.0f, 0.0f, is created, which means that there are 3 control points.
+ * You can add as many control points as you want, but they will be linearly spaced.
+ * Then you can apply the linear constrainer by using the alpha of the actor as the
+ * target and the source as the actor’s position.
  * @SINCE_1_0.0
  */
 class DALI_IMPORT_API LinearConstrainer : public Handle
@@ -67,26 +75,26 @@ public:
    * @brief Create an initialized LinearConstrainer handle.
    *
    * @SINCE_1_0.0
-   * @return a handle to a newly allocated Dali resource.
+   * @return A handle to a newly allocated Dali resource.
    */
   static LinearConstrainer New();
 
   /**
-   * @brief Downcast an Object handle to LinearConstrainer handle.
+   * @brief Downcast a handle to LinearConstrainer handle.
    *
    * If handle points to a LinearConstrainer object the downcast produces
    * valid handle. If not the returned handle is left uninitialized.
    * @SINCE_1_0.0
-   * @param[in] handle to An object
-   * @return handle to a LinearConstrainer object or an uninitialized handle
+   * @param[in] handle Handle to an object
+   * @return Handle to a LinearConstrainer object or an uninitialized handle
    */
   static LinearConstrainer DownCast( BaseHandle handle );
 
   /**
    * @brief Create an uninitialized LinearConstrainer handle.
    *
-   * This can be initialized with PathConstrainer::New(). Calling member
-   * functions with an uninitialized Dali::Object is not allowed.
+   * This can be initialized with @ref LinearConstrainer::New
+   * Calling member functions with an uninitialized LinearConstrainer handle is not allowed.
    * @SINCE_1_0.0
    */
   LinearConstrainer();
@@ -121,9 +129,9 @@ public:
    *
    * @SINCE_1_0.0
    * @param[in] target Property to be constrained
-   * @param[in] source Property used as parameter for the path
+   * @param[in] source Property used as parameter for the linear map
    * @param[in] range The range of values in the source property which will be mapped to [0,1]
-   * @param[in] wrap Wrapping domain. Source property will be wrapped in the domain [wrap.x,wrap.y] before mapping to [0,1]
+   * @param[in] wrap Wrapping domain. Source property will be wrapped in the domain [wrap.x,wrap.y] before mapping to [0,1]. See cfloat.h for FLT_MAX
    */
   void Apply( Dali::Property target, Dali::Property source, const Vector2& range, const Vector2& wrap = Vector2(-FLT_MAX, FLT_MAX) );
 
@@ -137,12 +145,12 @@ public:
 
 public: // Not intended for application developers
   /**
-   * @brief This constructor is used by Dali::New() methods.
+   * @brief This constructor is used by LinearConstrainer::New() methods.
    *
    * @SINCE_1_0.0
-   * @param[in] pathConstrainer A pointer to an internal PathConstrainer resource
+   * @param[in] internal A pointer to an internal LinearConstrainer resource
    */
-  explicit DALI_INTERNAL LinearConstrainer(Internal::LinearConstrainer* pathConstrainer);
+  explicit DALI_INTERNAL LinearConstrainer(Internal::LinearConstrainer* internal);
 };
 
 /**
index 30f6cda..7ecd505 100644 (file)
@@ -37,7 +37,7 @@ class Path;
 /**
  * @brief A 3D parametric curve
  *
- * Paths can be used to animate position and orientation of actors using Dali::Animate( Actor, Path, ... )
+ * Paths can be used to animate position and orientation of actors using @ref Dali::Animate( Actor, Path, ... )
  *
  * @SINCE_1_0.0
  */
@@ -62,26 +62,26 @@ public:
    * @brief Create an initialized Path handle.
    *
    * @SINCE_1_0.0
-   * @return a handle to a newly allocated Dali resource.
+   * @return A handle to a newly allocated Dali resource.
    */
   static Path New();
 
   /**
-   * @brief Downcast an Object handle to Path handle.
+   * @brief Downcast a handle to Path handle.
    *
-   * If handle points to a KeyFrames object the downcast produces
+   * If handle points to a Path object the downcast produces
    * valid handle. If not the returned handle is left uninitialized.
    * @SINCE_1_0.0
-   * @param[in] handle to An object
-   * @return handle to a Path object or an uninitialized handle
+   * @param[in] handle Handle to an object
+   * @return Handle to a Path object or an uninitialized handle
    */
   static Path DownCast( BaseHandle handle );
 
   /**
    * @brief Create an uninitialized Path handle.
    *
-   * This can be initialized with Path::New(). Calling member
-   * functions with an uninitialized Dali::Object is not allowed.
+   * This can be initialized with Path::New().
+   * Calling member functions with an uninitialized Path handle is not allowed.
    * @SINCE_1_0.0
    */
   Path();
@@ -133,8 +133,8 @@ public:
    * The generating algorithm is as follows:
    * For a given knot point K[N], find the vector that bisects K[N-1],[N] and [N],[N+1].
    * Calculate the tangent vector by taking the normal of this bisector.
-   * The in control point is the length of the preceding segment back along this bisector multiplied by the curvature
-   * The out control point is the length of the succeeding segment forward along this bisector multiplied by the curvature
+   * The in control point is the length of the preceding segment back along this bisector multiplied by the curvature.
+   * The out control point is the length of the succeeding segment forward along this bisector multiplied by the curvature.
    *
    * @SINCE_1_0.0
    * @param[in] curvature The curvature of the spline. 0 gives straight lines between the knots,
@@ -185,7 +185,7 @@ public:
 
 public: // Not intended for application developers
   /**
-   * @brief This constructor is used by Dali::New() methods.
+   * @brief This constructor is used by Path::New() methods.
    *
    * @SINCE_1_0.0
    * @param[in] path A pointer to an internal path resource