documenting that on() handler accepts .trigger() args #472

[mattlunn]

See #472 for the complete story. Basically;

1. Added extraParameter to the signature, and added further documentation as to how it works. It uses the rest="true" vararg attribute, which currently doesn't show anything, but support is being added in API Sites: Support for varargs grunt-jquery-content#56
2. Added examples of using on() and trigger().
3. Various tidyings

... all separated into separate commits.

[scottgonzalez]

I think it'd be better to use a more descriptive variable name here. Perhaps person instead of extraParameter.

[mattlunn]

Humm. I consciously used that variable name so that it matched the extraParameter variable name in the signature definition at the top of the on() docs; that way it'd be a CTRL + F match for anyone wondering WTF the extraParameter variable was in the signature (as otherwise it wouldn't be searchable).

I'm not sure whether you'd prefer CTRL + F goodness over good variable names; I'm open to change it.

[scottgonzalez]

I personally don't like having demos with bad variable names (demos should show how real code should be written). I'm fine with whatever the consensus is.

[kswedberg]

I like person, fwiw.

[mattlunn]

Happy to go with the consensus as well; PR updated to use person instead of extraParameter.

[scottgonzalez]

Thanks, this whole PR looks good to me; just one minor nit (in an inline comment).

I've landed the change in grunt-jquery-content and updated to the new version in 3cb7ccf. I've confirmed that rebasing this on master results in the correct output. I'll wait for @dmethvin to also review.

[kswedberg]

@dmethvin, can you please review this, per @scottgonzalez's comment above, so we can merge this in? Thanks.

[dmethvin]

LGTM!

[falsandtru]

Updates of this document we need.
TypeScript definition file of jQuery is dependent on the official API.

DefinitelyTyped does not fix the definition unless update the official api document. DefinitelyTyped prohibits the not one argument event handler reason in the official api document.

[falsandtru]

There was a good example to "extend". Better this seems good.

http://api.jquery.com/jQuery.extend/

<argument name="eventObject" type="Event" />
<argument name="extraParameter1" type="Anything" optional="true" rest="true" />
<argument name="extraParameterN" type="Anything" optional="true" rest="true" />

[mattlunn]

@falsandtru: Correct me if I'm wrong, but your comments are in reference to your PR DefinitelyTyped/DefinitelyTyped#2843.

You've got a point... all jQuery event methods (both the "lower level" on()'s etc, down to the shortcut click() etc's have the signature where extra arguments can be passed to it via trigger() (so I'm saying the changes you made in the PR to add the varargs to the event handlers for each of these are actually correct; they're just not documented in jQuery).

Currently, this PR only handles the case for on(). If we're going to merge this, I should probably expand this PR and add the trigger args to all the event handlers...

[falsandtru]

I ask you to fix because it seems I do not have permission to edit commit this request.
I know that there is a need for me to also modify other documents. However, the correct modification method is not yet known. So, I'm going to fix the other documents from being this request merged.
But it is time-consuming. So even better if you fix together also other documents.