Event: Warn and fill event aliases

Fixes #230
Closes #243

Author: dmethvin

src/event.js

@@ -75,6 +75,20 @@ jQuery.each( [ "load", "unload", "error" ], function( _, name ) {
 
 } );
 
+jQuery.each( ( "blur focus focusin focusout resize scroll click dblclick " +
+	"mousedown mouseup mousemove mouseover mouseout mouseenter mouseleave " +
+	"change select submit keydown keypress keyup contextmenu" ).split( " " ),
+	function( i, name ) {
+
+	// Handle event binding
+	jQuery.fn[ name ] = function( data, fn ) {
+		migrateWarn( "jQuery.fn." + name + "() event shorthand is deprecated" );
+		return arguments.length > 0 ?
+			this.on( name, null, data, fn ) :
+			this.trigger( name );
+	};
+} );
+
 // Trigger "ready" event only once, on document ready
 jQuery( function() {
 	jQuery( window.document ).triggerHandler( "ready" );
@@ -107,5 +121,9 @@ jQuery.fn.extend( {
 		return arguments.length === 1 ?
 			this.off( selector, "**" ) :
 			this.off( types, selector || "**", fn );
+	},
+	hover: function( fnOver, fnOut ) {
+		migrateWarn( "jQuery.fn.hover() is deprecated" );
+		return this.on( "mouseenter", fnOver ).on( "mouseleave", fnOut || fnOver );
 	}
 } );

test/event.js

@@ -94,6 +94,39 @@ QUnit.test( ".delegate() and .undelegate()", function( assert ) {
 	} );
 } );
 
+QUnit.test( "Event aliases", function( assert) {
+	assert.expect( 14 );
+
+	var $div = jQuery( "<div />" );
+
+	"scroll click submit keydown".split( " " ).forEach( function( name ) {
+		expectWarning( "." + name + "()", 1, function() {
+			$div[ name ]( function( event ) {
+				assert.equal( event.type, name, name );
+				$div.off( event );
+			} )[ name ]();
+		} );
+	} );
+
+	expectWarning( ".hover() one-arg", 1, function() {
+		$div.hover( function( event ) {
+			assert.ok( /mouseenter|mouseleave/.test( event.type ), event.type );
+			$div.off( event );
+		} ).trigger( "mouseenter" ).trigger( "mouseleave" );
+	} );
+
+	expectWarning( ".hover() two-arg", 1, function() {
+		$div.hover(
+			function( event ) {
+				assert.equal( "mouseenter", event.type, event.type );
+			},
+			function( event ) {
+				assert.equal( "mouseleave", event.type, event.type );
+			}
+		).trigger( "mouseenter" ).trigger( "mouseleave" );
+	} );
+} );
+
 test( "custom ready", function( assert ) {
 	assert.expect( 2 );
 

warnings.md

@@ -211,3 +211,15 @@ See jQuery-ui [commit](https://github.com/jquery/jquery-ui/commit/c0093b599fcd58
 **Cause:** Older versions of JavaScript made it difficult to determine if a particular object was a true `Array`, so jQuery provided a cross-browser function to do the work. The browsers supported by jQuery 3.0 all provide `Array.isArray(obj)` for this purpose.
 
 **Solution**: Replace any calls to `jQuery.isArray` with `Array.isArray`.
+
+### JQMIGRATE: jQuery.fn.click() event shorthand is deprecated
+
+**Cause:** The `.on()` and `.trigger()` methods can set an event handler or generate an event for any event type, and should be used instead of the shortcut methods. This message also applies to the other event shorthands, including: blur, focus, focusin, focusout, resize, scroll, dblclick, mousedown, mouseup, mousemove, mouseover, mouseout, mouseenter, mouseleave, change, select, submit, keydown, keypress, keyup, and contextmenu.
+
+**Solution:** Instead of `.click(fn)` use `.on("click", fn)`. Instead of `.click()` use `.trigger("click")`.
+
+### JQMIGRATE: jQuery.fn.hover() is deprecated
+
+**Cause:** The `.hover()` method is a shorthand for the use of the `mouseover`/`mouseout` events. It is often a poor user interface choice because it does not allow for any small amounts of delay between when the mouse enters or exits an area and when the event fires. This can make it quite difficult to use with UI widgets such as drop-down menus.  For more information on the problems of hovering, see the [hoverIntent plugin](http://cherne.net/brian/resources/jquery.hoverIntent.html).
+
+**Solution:** Review uses of `.hover()` to determine if they are appropriate, and consider use of plugins such as `hoverIntent` as an alternative. The direct replacement for `.hover(fn1, fn2)`, is `.on("mouseenter", fn1).on("mouseleave", fn2)`.