$.ready documentation

[PixievoltNo1]

Ticket #11470 brought a ready promise to jQuery 1.8, but it's not in the API docs yet.

[dmethvin]

I want to introduce the ability to exclude both $.Deferred and $.Callbacks in 1.11 so let's wait until that's finalized before documenting this.

[dmethvin]

Still not convinced this should be documented in situ since it's rather awkwardly placed. We need to determine how Promises will be handled in general for 1.12.

[he7d3r]

Any news on this?

[timmywil]

Rather than introducing the ability to exclude $.Deferred, we've introduced the ability to exclude .ready(). I think it's safe to document that is supports the jQuery Promise API.

[Krinkle]

I'm not sure I see how Promise/Deferred possibly being excludable affects our decision about documenting this as a public API?

ajax can be excluded from the build as well, yet jQuery.ajax is a public API we support and document. Whether we want to support jQuery.read.promise() should be a fairly simple question (regardless of it being in module core, ready, deferred, or otherwise).

We also have $().promise in our API, and $().ready.

[timmywil]

I'm not sure I see how Promise/Deferred possibly be excluded affects our decision about including this in the public API?

I see the argument. Documenting it implies a guarantee that Deferred will be present when using .ready(). Dave is thinking about future APIs as well as the current one. However, 1.11 has been finalized so I think we're good to document this.

[arthurvr]

PR #530.

[dmethvin]

I still don't think we should document jQuery.ready.promise() because that implies jQuery.ready is a jQuery.Deferred-like object with a .promise() method. Instead, I'd like to document that jQuery.ready is accepted as a deferred/promise in APIs such as jQuery.when(). The distinction is subtle perhaps, but means that someone could exclude jQuery.Deferred but put in their own jQuery.ready implementation based on, for example, a native Promise, but still maintain decent interoperability. Does that seem sane?

[gibson042]

I agree with that approach. The method is essentially an internal implementation detail for enabling things like jQuery.when( jQuery.ready ) or (hopefully) Promise.resolve( jQuery.ready ).

[dmethvin]

The blueprint for exposing the ready promise is set in this comment by @gibson042. Basically, we're not documenting it to be a jQuery.Deferred but instead a thenable that is generally compatible with other promise mechanisms including jQuery.when and the standard Promise.resolve. I've updated the title of this issue to reflect that.

[dmethvin]

Also note that this approach is back-compatible so we can document it for existing versions and not just 3.0.

[benjamingr]

Yeah, the point of the other (dupe) issue is that it's back compatible, you're likely not going to break 1.x or 2.x anyway and it'd be beneficial to document it since people are already using it when using promises anyway (passing it to Promise.all is pretty common when you want to wait for the page to load and to make an AJAX request for data).

Thanks for considering. I'd love to use this.

[benjamingr]

ping.