$.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.