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 :)

[dmethvin]

Maybe I'm wrong but I just have a feeling this is a lot of work for little reward to expose something that isn't a mainstream need. Creating additional public API surface limits what we can do in the future. That's why I proposed not documenting them above.

Another concern is the remaining work required to fully document and support these APIs. Besides docs, there are no unit tests that specifically check Tween or Animation directly and it seems we should have those if we're calling them documented APIs. Most likely if people do start to use these we'll find that there are edge cases we need to fix that don't occur in our own .animate() usage.

Maybe these fit into a gray-area category with special events hooks, prophooks, attrhooks, and valhooks. (Really, in my mind Callbacks fit here too.) All of those are exposed and it's possible for anyone to use them, but it's usually better that they don't. Documenting any of those too prominently make them appear to be more important than they are to the majority of developers.

Ultimately, a decision to change this won't matter unless we have someone to do the work. Otherwise we're going to continue with the status quo of the gist above for docs and pseudo-support.

[arthurvr]

We should probably discuss at a core meeting cc @jquery/core if we want to continue to maintain these APIs.

@timmywil @dmethvin Could we drop this into the core meeting agenda for the Mon 4/13? gnarf said he wasn't available today.

[timmywil]

@arthurvr yup

[rusterholz]

Any update on this? According to @arthurvr the core team discussed this almost a year ago, on 2015-04-13. Was a decision reached? Has any work been done to move this ahead? I'm working on a project and could really use some documentation on the Tween object.

@dmethvin How exactly do you determine which parts of the public API are "mainstream needs" and which are not? If they're not mainstream needs, and the team doesn't want to maintain them, then they should probably be removed from the public API entirely (i.e. stop passing Tween objects to any functions that a user might define, like the step function on animations -- then there would be no need for that user to know how to work with a Tween object). Contrariwise, if they need to be left in the public API (if they must continue to be passed to such functions), then isn't that "mainstream" enough to be worth documenting and maintaining them along with the rest of the API?

The larger question that I don't understand, even after re-reading the discussion above, is: Why would documenting Tween objects, and updating that documentation for new versions, be any more onerous of a task than documenting the other types that are passed to user-defined functions and keeping their documentation updated for new versions?

[dmethvin]

Nothing is hard if someone volunteers to do it. That's why this is labeled "help wanted", we just need someone motivated to do the work. If you are interested in this API it would be a great way to learn! Experience shows that once you document something and people start to use it, they will find problems and edge cases that need to be fixed in the code or documentation. So it's good to plan on a little bit of followup over time.