Effects 1.8 needs documentation

[gnarf]

I started up draft docs over on https://gist.github.com/54829d408993526fe475

We need to get these new methods and options documented.

[gnarf]

See #81 for a small part of it

[kswedberg]

Thanks, @gnarf37, for posting this issue. It's been on my mind for some time. I created a feature branch called animate-1.8 that I'm going to push some updates to so you can review them before merging into master.

[arthurvr]

This issue has been open for more than 2 years. @kswedberg what is your status on this? It probably needs some more changes since this issue is really old.

[dmethvin]

My current thinking is that we should not document the additional interfaces, in which case this could be closed. Any objections?

[kswedberg]

sounds good to me

[kswedberg]

@gnarf?

[arthurvr]

Sounds fine.

[scottgonzalez]

These are APIs driven by real developer needs. They were created to be public and should be documented.

[dmethvin]

I don't see a compelling reason to expand our API surface for this. It doesn't solve a need that jQuery users have expressed. We haven't gotten a lot of complaints (as in none that I can think of) about them not being documented. There was some talk about allowing Velocity.js to be slotted in and excluding ours, but its compatibility stops at .animate() and doesn't include the APIs mentioned here.

[gauthierm]

Am I to understand from this that use of the jQuery.Animation and jQuery.Tween APIs is discouraged? I'm converting a project to use jQuery and have a need for the more advanced APIs. I was happy to see they exist but disappointed there is no documentation.

The 1.8 release notes seem to suggest the new APIs are available for developers and are just waiting to be documented.

[gnarf]

These more advanced APIs are really useful - they were inspired and created to solve real problems we faced in the jQuery UI effects suite. Try writing an animation that is a chain of 3 animations in a row, it requires better lower level animation control that jQuery didn't offer before 1.8, the current method uses hacks around the .queue() interface and cssHooks. We don't use them yet in UI because we hadn't had enough "minimum jQuery" requirement to ensure they existed.

If @dmethvin / core team already wants to deprecate the 1.8 APIs I suppose we could just "never document" them, but I think it would be nice to encourage the use of the lower level APIs. I imagine @gauthierm is not the only developer excited to see these lower level primitives. We should probably discuss at a core meeting cc @jquery/core if we want to continue to maintain these APIs.

My draft documentation should still be accurate, and my time on "review" of this documentation is available. @kswedberg and I worked together on some docs at one point, but I don't know what came of any of that.

[arthurvr]

whoops stupid github :)