diff --git a/event/drag/drag.js b/event/drag/drag.js
index f930b07f..722a5b83 100644
--- a/event/drag/drag.js
+++ b/event/drag/drag.js
@@ -567,51 +567,67 @@ steal('jquery/event', 'jquery/lang/vector', 'jquery/event/livehack', function( $
}
}
});
-
/**
- * @add jQuery.event.drag
+ * @add jQuery.event.special
*/
event.setupHelper([
/**
* @attribute dragdown
- *
+ * @parent jQuery.event.drag
+ *
* `dragdown` is called when a drag movement has started on a mousedown.
* The event handler gets an instance of [jQuery.Drag] passed as the second
- * parameter.
- * If you listen to this, the mousedown's default event (preventing
- * text selection) is not prevented. You are responsible for calling it
+ * parameter. Listening to `dragdown` allows you to customize
+ * the behavior of a drag motion, especially when `draginit` should be called.
+ *
+ * $(".handles").delegate("dragdown", function(ev, drag){
+ * // call draginit only when the mouse has moved 20 px
+ * drag.distance(20);
+ * })
+ *
+ * Typically, when a drag motion is started, `event.preventDefault` is automatically
+ * called, preventing text selection. However, if you listen to
+ * `dragdown`, this default behavior is not called. You are responsible for calling it
* if you want it (you probably do).
*
- * ## Why might you not want it?
+ * ### Why might you not want to call `preventDefault`?
*
* You might want it if you want to allow text selection on element
* within the drag element. Typically these are input elements.
*
- * $(".handles").delegate("dragdown", function(ev, drag){})
+ * $(".handles").delegate("dragdown", function(ev, drag){
+ * if(ev.target.nodeName === "input"){
+ * drag.cancel();
+ * } else {
+ * ev.preventDefault();
+ * }
+ * })
*/
'dragdown',
/**
* @attribute draginit
+ * @parent jQuery.event.drag
*
* `draginit` is triggered when the drag motion starts. Use it to customize the drag behavior
* using the [jQuery.Drag] instance passed as the second parameter:
*
- * $(".draggable").on('draginit', function(ev, drag) {
- * // Only allow vertical drags
- * drag.vertical();
- * // Create a draggable copy of the element
- * drag.ghost();
- * });
+ * $(".draggable").on('draginit', function(ev, drag) {
+ * // Only allow vertical drags
+ * drag.vertical();
+ * // Create a draggable copy of the element
+ * drag.ghost();
+ * });
*/
'draginit',
/**
* @attribute dragover
+ * @parent jQuery.event.drag
*
* `dragover` is triggered when a drag is over a [jQuery.event.drop drop element].
* The event handler gets an instance of [jQuery.Drag] passed as the second
- * parameter.
+ * parameter and an instance of [jQuery.Drop] passed as the third argument:
*
- * $('.draggable').on('dragover', function(ev, drag) {
+ * $('.draggable').on('dragover', function(ev, drag, drop) {
* // Add the drop-here class indicating that the drag
* // can be dropped here
* drag.element.addClass('drop-here');
@@ -620,11 +636,12 @@ steal('jquery/event', 'jquery/lang/vector', 'jquery/event/livehack', function( $
'dragover',
/**
* @attribute dragmove
+ * @parent jQuery.event.drag
*
* `dragmove` is triggered when the drag element moves (similar to a mousemove).
* The event handler gets an instance of [jQuery.Drag] passed as the second
* parameter.
- * Use [jQuery.Drag.prototype.location] to determine the current position
+ * Use [jQuery.Drag::location] to determine the current position
* as a [jQuery.Vector vector].
*
* For example, `dragmove` can be used to create a draggable element to resize
@@ -638,6 +655,7 @@ steal('jquery/event', 'jquery/lang/vector', 'jquery/event/livehack', function( $
'dragmove',
/**
* @attribute dragout
+ * @parent jQuery.event.drag
*
* `dragout` is called when the drag leaves a drop point.
* The event handler gets an instance of [jQuery.Drag] passed as the second
@@ -653,14 +671,15 @@ steal('jquery/event', 'jquery/lang/vector', 'jquery/event/livehack', function( $
'dragout',
/**
* @attribute dragend
+ * @parent jQuery.event.drag
*
* `dragend` is called when the drag motion is done.
* The event handler gets an instance of [jQuery.Drag] passed as the second
* parameter.
*
- * $('.draggable').on('dragend', function(ev, drag)
- * // Clean up when the drag motion is done
- * });
+ * $('.draggable').on('dragend', function(ev, drag)
+ * // Clean up when the drag motion is done
+ * });
*/
'dragend'], "mousedown", function( e ) {
$.Drag.mousedown.call($.Drag, e, this);
diff --git a/event/drag/step/step.html b/event/drag/step/step.html
index 664375fc..80c20c46 100644
--- a/event/drag/step/step.html
+++ b/event/drag/step/step.html
@@ -44,9 +44,11 @@
horizontal vertical
-
+
diff --git a/event/drag/step/step.js b/event/drag/step/step.js
index 943b3679..a31d7e22 100644
--- a/event/drag/step/step.js
+++ b/event/drag/step/step.js
@@ -20,7 +20,12 @@ steal('jquery/event/drag', 'jquery/dom/styles').then(function( $ ) {
*
* @demo jquery/event/drag/step/step.html
*
- * @param {number|Object} amount make the drag move X amount in pixels from the top-left of container.
+ * @param {number|Object} amount make the drag move the amount in pixels from the top-left of container.
+ *
+ * If the amount is a `number`, the drag will move step-wise that number pixels in both
+ * dimensions. If it's an object like `{x: 20, y: 10}` the drag will move in steps 20px from
+ * left to right and 10px up and down.
+ *
* @param {jQuery} [container] the container to move in reference to. If not provided, the document is used.
* @param {String} [center] Indicates how to position the drag element in relationship to the container.
*