jQuery on() docs

Question

Are the docs for jQuery's on() function incorrect (or unclear)? Consider this code:

<div>
    <span>
        <div>
            <input type="button" value="click me!" />
        </div>
    </span>
</div>

$(document).on("click", function() {
    console.log(this.toString());
});

The docs state

selector A selector string to filter the descendants of the selected elements that trigger the event. If the selector is null or omitted, the event is always triggered when it reaches the selected element.

Clicking the button only causes one console.log for the document itself, while $(document).on("click", "*", function()... causes many.

I know the Stack Overflow community isn't responsible for the jQuery docs, but shouldn't they say that when the selector is omitted, the event is only triggered when it reaches the selected element? Or is there something about event delegation I'm not understanding correctly?

Complete fiddle

Answer 1

There is no event delegation when you leave the selector out. From the docs:

If selector is omitted or is null, the event handler is referred to as direct or directly-bound. The handler is called every time an event occurs on the selected elements, whether it occurs directly on the element or bubbles from a descendant (inner) element.

When a selector is provided, the event handler is referred to as delegated. The handler is not called when the event occurs directly on the bound element, but only for descendants (inner elements) that match the selector. jQuery bubbles the event from the event target up to the element where the handler is attached (i.e., innermost to outermost element) and runs the handler for any elements along that path matching the selector.

Basically .on is doing the jQuery thing -- it is overloaded to do completely different things depending on arguments. Personally I prefer .delegate for delegation, and .bind for normal events, as they are much clearer and I hope they don't get removed in later versions.

Answer 2

Personally I think it's clear enough. When the selector is omitted the event is triggered when it reaches the selected element. The word "always" doesn't really change the meaning in my opinion. The event will always be triggered when it reaches the selected element (note that if something like stopPropagation is called, the event will not reach the selected element and therefore won't be triggered).

When a selector is present, the event is triggered when it reaches the selected element having originated from an element matching the selector.

When you use the universal selector * every single element between the event target and the selected element will trigger the event.

As you stated in your comment, on provides all the functionality you need to bind events in jQuery 1.7+:

As of jQuery 1.7, the .on() method provides all functionality required for attaching event handlers.