Jason, I know this wasn't really your point, which was about having better docs and not the TweenEffect API specifically, but for what it's worth: the new effects for the next release of Flex, along with the Animation class (which is used instead of Tween), avoid the use of Function handles for easing and update/end handlers. Instead, we use interfaces for easing (and for type interpolation, a new concept in the effects). And events are sent through event handlers. Hopefully this all makes it more explicit what's happening to whom and what developers need to know about it...
Chet. From: flexcoders@yahoogroups.com [mailto:[EMAIL PROTECTED] On Behalf Of Pan Troglodytes Sent: Thursday, September 11, 2008 9:32 AM To: flexcoders Subject: [flexcoders] Note to someone at Adobe who is in charge of documentation Hopefully, someone who reads this can maybe forward it or mention it to someone who is in the documentation department. My biggest problem with the documentation is when it comes to function signatures. Unfortunately in ActionScript, function signatures are not "typeable". If I was using Delphi, I could define TMyEventCallback = function (param1: String, param2: Integer):Boolean; So properties always just take a "Function" and it's up to the developer to figure out what the function should look like. Okay, I can deal with that, given proper documentation. But so many times in the docs, no function signature is listed. I understand that it's hard to create docs while the SDK is still under development, however there are plenty of examples of it in code that shipped with 2.0. For example, from TweenEffect: easingFunction property public var easingFunction:Function<../../Function.html> = null The easing function for the animation. The easing function is used to interpolate between the initial value and the final value. A trivial easing function would simply do linear interpolation, but more sophisticated easing functions create the illusion of acceleration and deceleration, which makes the animation seem more natural. If no easing function is specified, an easing function based on the Math.sin() method is used. The easing function follows the function signature popularized by Robert Penner. The function accepts four arguments. The first argument is the "current time", where the animation start time is 0. The second argument is the initial value at the beginning of the animation (a Number). The third argument is the ending value minus the initial value. The fourth argument is the duration of the animation. The return value is the interpolated value for the current time. This is usually a value between the initial value and the ending value. The value of this property must be a function object. Flex includes a set of easing functions in the mx.effects.easing package. This documentation is strange in that a paragraph is dedicated to describing the function signature, when just putting a function (currentTime:Number, startValue:Number, endValueMinusStartValue:Number, duration:Number):Number alone would have been far more useful than the whole paragraph. I'm not saying to ditch the paragraph, but a code examples is almost always preferable. Especially since that paragraph forgot to specify that the last two params and teh return param should be a Number. This was inferable from context in this case, but it is not always. These omissions tend to send me on a code hunt, looking for some place in the SDK where the function is called. For easingFunction, this was quite a bit of digging until I finally found defaultEasingFunction in Tween.as. I could put this in as a bug/enhancement, but it just seems like that falls short. I'd really just like to see more of a focus on doing it properly the first time and possibly doing a review of all documentation that mentions a property or method that involves a type Function. -- Jason
