diff --git a/src/dom/event.js b/src/dom/event.js
index 705a7dee7..d06fa48a9 100644
--- a/src/dom/event.js
+++ b/src/dom/event.js
@@ -480,35 +480,37 @@
/**
* Event.observe(element, eventName, handler) -> Element
* - element (Element | String): The DOM element to observe, or its ID.
- * - eventName (String): The name of the event, in all lower case, without the "on"
- * prefix — e.g., "click" (not "onclick").
+ * - eventName (String): The name of the event, in all lower case, without
+ * the "on" prefix — e.g., "click" (not "onclick").
* - handler (Function): The function to call when the event occurs.
*
* Registers an event handler on a DOM element. Aliased as [[Element#observe]].
*
- * `Event.observe` smooths out a variety of differences between browsers and provides
- * some handy additional features as well. Key features in brief:
+ * [[Event.observe]] smooths out a variety of differences between browsers
+ * and provides some handy additional features as well. Key features in brief:
* * Several handlers can be registered for the same event on the same element.
* * Prototype figures out whether to use `addEventListener` (W3C standard) or
* `attachEvent` (MSIE); you don't have to worry about it.
* * The handler is passed an _extended_ [[Event]] object (even on MSIE).
- * * The handler's context (`this` value) is set to the extended element being observed
- * (even if the event actually occurred on a descendent element and bubbled up).
- * * Prototype handles cleaning up the handler when leaving the page (important for MSIE memory
- * leak prevention).
- * * `observe` makes it possible to stop observing the event easily via [[Event.stopObserving]].
- * * Adds support for `mouseenter` / `mouseleave` in all browsers.
- *
- * Although you can use `Event.observe` directly and there are times when that's the most
- * convenient or direct way, it's more common to use its alias [[Element#observe]]. These two
- * statements have the same effect:
+ * * The handler's context (`this` value) is set to the extended element
+ * being observed (even if the event actually occurred on a descendent
+ * element and bubbled up).
+ * * Prototype handles cleaning up the handler when leaving the page
+ * (important for MSIE memory leak prevention).
+ * * [[Event.observe]] makes it possible to stop observing the event easily
+ * via [[Event.stopObserving]].
+ * * Adds support for `mouseenter` / `mouseleave` events in all browsers.
+ *
+ * Although you can use [[Event.observe]] directly and there are times when
+ * that's the most convenient or direct way, it's more common to use its
+ * alias [[Element#observe]]. These two statements have the same effect:
*
* Event.observe('foo', 'click', myHandler);
* $('foo').observe('click', myHandler);
*
* The examples in this documentation use the [[Element#observe]] form.
*
- *
The Handler
+ * ##### The Handler
*
* Signature:
*
@@ -516,35 +518,39 @@
* // `this` = the element being observed
* }
*
- * So for example, this will turn the background of the element 'foo' blue when it's clicked:
+ * So for example, this will turn the background of the element 'foo' blue
+ * when it's clicked:
*
* $('foo').observe('click', function(event) {
* this.setStyle({backgroundColor: 'blue'});
* });
*
- * Note that we used `this` to refer to the element, and that we received the `event` object
- * as a parameter (even on MSIE).
+ * Note that we used `this` to refer to the element, and that we received the
+ * `event` object as a parameter (even on MSIE).
*
- * It's All About Timing
+ * ##### It's All About Timing
*
- * One of the most common errors trying to observe events is trying to do it before the element
- * exists in the DOM. Don't try to observe elements until after the
- * [[document.observe dom:loaded]] event or `window` `load` event has been fired.
+ * One of the most common errors trying to observe events is trying to do it
+ * before the element exists in the DOM. Don't try to observe elements until
+ * after the [[document.observe dom:loaded]] event or `window` `load` event
+ * has been fired.
*
- * Preventing the Default Event Action and Bubbling
+ * ##### Preventing the Default Event Action and Bubbling
*
- * If we want to stop the event (e.g., prevent its default action and stop it bubbling), we can
- * do so with the extended event object's [[Event#stop]] method:
+ * If we want to stop the event (e.g., prevent its default action and stop it
+ * bubbling), we can do so with the extended event object's [[Event#stop]]
+ * method:
*
* $('foo').observe('click', function(event) {
* event.stop();
* });
*
- * Finding the Element Where the Event Occurred
+ * ##### Finding the Element Where the Event Occurred
*
- * Since most events bubble from descendant elements up through the hierarchy until they're
- * handled, we can observe an event on a container rather than individual elements within the
- * container. This is sometimes called "event delegation". It's particularly handy for tables:
+ * Since most events bubble from descendant elements up through the hierarchy
+ * until they're handled, we can observe an event on a container rather than
+ * individual elements within the container. This is sometimes called "event
+ * delegation". It's particularly handy for tables:
*
*
*
@@ -560,27 +566,27 @@
* Instead of observing each cell or row, we can simply observe the table:
*
* $('records').observe('click', function(event) {
- * var clickedRow;
- * clickedRow = event.findElement('tr');
+ * var clickedRow = event.findElement('tr');
* if (clickedRow) {
* this.down('th').update("You clicked record #" + clickedRow.readAttribute("data-recnum"));
* }
* });
*
- * When any row in the table is clicked, we update the table's first header cell saying which
- * record was clicked. [[Event#findElement]] finds the row that was clicked, and `this` refers
- * to the table we were observing.
+ * When any row in the table is clicked, we update the table's first header
+ * cell saying which record was clicked. [[Event#findElement]] finds the row
+ * that was clicked, and `this` refers to the table we were observing.
*
- * Stopping Observing the Event
+ * ##### Stopping Observing the Event
*
- * If we don't need to observe the event anymore, we can stop observing it with
- * [[Event.stopObserving]] (aka [[Element#stopObserving]]).
+ * If we don't need to observe the event anymore, we can stop observing it
+ * with [[Event.stopObserving]] or its [[Element#stopObserving]] alias.
*
- * Using an Instance Method as a Handler
+ * ##### Using an Instance Method as a Handler
*
- * If we want to use an instance method as a handler, we will probably want to use
- * [[Function#bind]] to set the handler's context; otherwise, the context will be lost and
- * `this` won't mean what we expect it to mean within the handler function. E.g.:
+ * If we want to use an instance method as a handler, we will probably want
+ * to use [[Function#bind]] to set the handler's context; otherwise, the
+ * context will be lost and `this` won't mean what we expect it to mean
+ * within the handler function. E.g.:
*
* var MyClass = Class.create({
* initialize: function(name, element) {
@@ -595,28 +601,31 @@
* },
* });
*
- * Without the `bind`, when `handleClick` was triggered by the event, `this` wouldn't
- * refer to the instance and so the alert wouldn't show the name. Because we used `bind`, it
- * works correctly. See [[Function#bind]] for
- * details. There's also [[Function#bindAsEventListener]], which is handy for certain very
- * specific situations. (Normally, `bind` is all you need.)
+ * Without the [[Function#bind]], when `handleClick` was triggered by the
+ * event, `this` wouldn't refer to the instance and so the alert wouldn't
+ * show the name. Because we used [[Function#bind]], it works correctly. See
+ * [[Function#bind]] for details. There's also [[Function#bindAsEventListener]],
+ * which is handy for certain very specific situations. (Normally,
+ * [[Function#bind]] is all you need.)
*
- * Side Notes
+ * ##### Side Notes
*
- * Although Prototype smooths out most of the differences between browsers, the fundamental
- * behavior of a browser implementation isn't changed. For example, the timing of the `change`
- * or `blur` events varies a bit from browser to browser.
+ * Although Prototype smooths out most of the differences between browsers,
+ * the fundamental behavior of a browser implementation isn't changed. For
+ * example, the timing of the `change` or `blur` events varies a bit from
+ * browser to browser.
*
- * Changes in 1.6.x
+ * ##### Changes in 1.6.x
*
- * Prior to Prototype 1.6, `observe` supported a fourth argument (`useCapture`), a boolean that
- * indicated whether to use the browser's capturing phase or its bubbling phase. Since MSIE does
- * not support the capturing phase, we removed this argument from 1.6, lest it give users the
+ * Prior to Prototype 1.6, [[Event.observe]] supported a fourth argument
+ * (`useCapture`), a boolean that indicated whether to use the browser's
+ * capturing phase or its bubbling phase. Since MSIE does not support the
+ * capturing phase, we removed this argument from 1.6, lest it give users the
* false impression that they can use the capturing phase in all browsers.
*
- * 1.6 also introduced setting the `this` context to the element being observed, automatically
- * extending the [[Event]] object, and the [[Event#findElement]] method.
- *
+ * 1.6 also introduced setting the `this` context to the element being
+ * observed, automatically extending the [[Event]] object, and the
+ * [[Event#findElement]] method.
**/
function observe(element, eventName, handler) {
element = $(element);
@@ -651,18 +660,20 @@
/**
* Event.stopObserving(element[, eventName[, handler]]) -> Element
* - element (Element | String): The element to stop observing, or its ID.
- * - eventName (String): _(Optional)_ The name of the event to stop observing, in all lower case,
- * without the "on" — e.g., "click" (not "onclick").
- * - handler (Function): _(Optional)_ The handler to remove; must be the _exact same_ reference
- * that was passed to [[Event.observe]] (see below.).
+ * - eventName (String): _(Optional)_ The name of the event to stop
+ * observing, in all lower case, without the "on" — e.g.,
+ * "click" (not "onclick").
+ * - handler (Function): _(Optional)_ The handler to remove; must be the
+ * _exact same_ reference that was passed to [[Event.observe]].
*
* Unregisters one or more event handlers.
*
* If `handler` is omitted, unregisters all event handlers on `element`
* for that `eventName`. If `eventName` is also omitted, unregisters _all_
- * event handlers on `element`. (In each case, only affects handlers registered via Prototype.)
+ * event handlers on `element`. (In each case, only affects handlers
+ * registered via Prototype.)
*
- * Examples
+ * ##### Examples
*
* Assuming:
*
@@ -672,18 +683,21 @@
*
* $('foo').stopObserving('click', myHandler);
*
- * If we want to remove _all_ 'click' handlers from 'foo', we leave off the handler argument:
+ * If we want to remove _all_ 'click' handlers from 'foo', we leave off the
+ * handler argument:
*
* $('foo').stopObserving('click');
*
- * If we want to remove _all_ handlers for _all_ events from 'foo' (perhaps we're about to remove
- * it from the DOM), we simply omit both the handler and the event name:
+ * If we want to remove _all_ handlers for _all_ events from 'foo' (perhaps
+ * we're about to remove it from the DOM), we simply omit both the handler
+ * and the event name:
*
* $('foo').stopObserving();
*
- * A Common Error
+ * ##### A Common Error
*
- * When using instance methods as observers, it's common to use [[Function#bind]] on them, e.g.:
+ * When using instance methods as observers, it's common to use
+ * [[Function#bind]] on them, e.g.:
*
* $('foo').observe('click', this.handlerMethod.bind(this));
*
@@ -691,9 +705,10 @@
*
* $('foo').stopObserving('click', this.handlerMethod.bind(this)); // <== WRONG
*
- * [[Function#bind]] returns a _new_ function every time it's called, and so if you don't retain
- * the reference you used when observing, you can't unhook that function specifically. (You can
- * still unhook __all__ handlers for an event, or all handlers on the element entirely.)
+ * [[Function#bind]] returns a _new_ function every time it's called, and so
+ * if you don't retain the reference you used when observing, you can't
+ * unhook that function specifically. (You can still unhook __all__ handlers
+ * for an event, or all handlers on the element entirely.)
*
* To do this, you need to keep a reference to the bound function:
*
@@ -703,7 +718,6 @@
* ...and then to remove:
*
* $('foo').stopObserving('click', this.boundHandlerMethod); // <== Right
- *
**/
function stopObserving(element, eventName, handler) {
element = $(element);