.bind() overloads

[leonard-thieu]

Going off the documentation at http://api.jquery.com/bind/, the following overloads should be possible:

bind(eventType, eventData, handler)
bind(eventType, handler)
bind(eventType, eventData, preventBubble)
bind(eventType, eventData)
bind(eventType, preventBubble)
bind(eventType)
bind(events)

There's two overloads that pass event data without a user-supplied handler:

bind(eventType, eventData, preventBubble)
bind(eventType, eventData)

I'm not sure I understand the purposes of those two overloads. If you pass event data without an event handler, doesn't that mean you can never observe it?

Also, I believe this is the only method that documents accepting both true and false in place of a handler. Other methods only document allowing false. Does bind do anything special in this regard?

[dmethvin]

Yes, it would be a little silly to pass data for those two cases, I'm not sure it's allowed but if it is you shouldn't use it.. The .bind() method has been deprecated for several years so if any docs clarifications are needed they would be in the .on() method.

[leonard-thieu]

Thanks for the response. I've been working on the TypeScript type definitions for jQuery 3 which is why I was interested in the details.

I also did some testing in the meantime and got these results:

bind(eventType, eventData, handler) // Works
bind(eventType, eventData, false)   // Works, eventData not used
bind(eventType, handler)            // Works
bind(eventType, false)              // Works
bind(eventType)                     // Works, but does it do anything?
bind(events)                        // Works

bind(eventType, eventData, true)    // TypeError
bind(eventType, eventData)          // TypeError
bind(eventType, true)               // TypeError

[dmethvin]

The .bind(eventType) should be considered an error if called that way, but for compat reasons we've had to accept that .bind(eventType, undefined_or_null) must live.

Only false is allowed, true isn't valid. Sometimes the prose-based docs and pseudo-BNF can't express things perfectly.

[leonard-thieu]

The .bind(eventType) should be considered an error if called that way, but for compat reasons we've had to accept that .bind(eventType, undefined_or_null) must live.

Thanks for letting me know about that. It also clears up some of the confusion I had reading the source for bind/on.

[mgol]

@dmethvin We can still update the signature, can't we? The one in https://api.jquery.com/on/ seems to have it right.

[dmethvin]

@mgol Sure, if someone wanted to update the docs we could do that.

[mgol]

@leonard-thieu would you like to submit a PR?

[leonard-thieu]

I think I'll let someone else handle it.