diff --git a/src/ajax/periodical_updater.js b/src/ajax/periodical_updater.js
index 03fa516..51ddfe7 100644
--- a/src/ajax/periodical_updater.js
+++ b/src/ajax/periodical_updater.js
@@ -34,7 +34,7 @@
* is the same; when the result is different once again, `frequency` will
* revert to its original value.
*
- * Disabling and re-enabling a `PeriodicalUpdater`
+ * Disabling and re-enabling a PeriodicalUpdater
*
* You can hit the brakes on a running `PeriodicalUpdater` by calling
* [[Ajax.PeriodicalUpdater#stop]]. If you wish to re-enable it later, call
@@ -71,11 +71,24 @@ Ajax.PeriodicalUpdater = Class.create(Ajax.Base, {
this.start();
},
+ /**
+ * Ajax.PeriodicalUpdater#start() -> undefined
+ *
+ * Starts the periodical updater (if it had previously been stopped with
+ * [[Ajax.PeriodicalUpdater#stop]]).
+ **/
start: function() {
this.options.onComplete = this.updateComplete.bind(this);
this.onTimerEvent();
},
+ /**
+ * Ajax.PeriodicalUpdater#stop() -> undefined
+ *
+ * Stops the periodical updater.
+ *
+ * Also calls the `onComplete` callback, if one has been defined.
+ **/
stop: function() {
this.updater.options.onComplete = undefined;
clearTimeout(this.timer);
diff --git a/src/ajax/request.js b/src/ajax/request.js
index d09d53d..b19d5f4 100644
--- a/src/ajax/request.js
+++ b/src/ajax/request.js
@@ -12,7 +12,7 @@
* property will automatically be passed to `eval`.
*
* In other words: you don't even need to provide a callback to leverage
- * pure-JavaScript AJAX responses. This is the convention that drives Rails's
+ * pure-JavaScript Ajax responses. This is the convention that drives Rails's
* RJS.
*
* The list of JavaScript-related MIME-types handled by Prototype is:
@@ -182,7 +182,7 @@ Ajax.Request = Class.create(Ajax.Base, {
},
/**
- * Ajax.Request.success() -> Boolean
+ * Ajax.Request#success() -> Boolean
*
* Tests whether the request was successful.
**/
@@ -240,7 +240,7 @@ Ajax.Request = Class.create(Ajax.Base, {
},
/**
- * Ajax.Request.getHeader(name) -> String | null
+ * Ajax.Request#getHeader(name) -> String | null
* - name (String): The name of an HTTP header that may have been part of
* the response.
*
diff --git a/src/ajax/updater.js b/src/ajax/updater.js
index 036dbe8..c923d55 100644
--- a/src/ajax/updater.js
+++ b/src/ajax/updater.js
@@ -9,9 +9,9 @@
*
* Example
*
- * new Ajax.Updater('items', '/items', {
- * parameters: { text: $F('text') }
- * });
+ * new Ajax.Updater('items', '/items', {
+ * parameters: { text: $F('text') }
+ * });
*
* This example will make a request to the URL `/items` (with the given
* parameters); it will then replace the contents of the element with the ID
diff --git a/src/dom/dom.js b/src/dom/dom.js
index 1d58343..b293299 100644
--- a/src/dom/dom.js
+++ b/src/dom/dom.js
@@ -1863,5 +1863,28 @@ Element.addMethods({
}
return value;
+ },
+
+ /**
+ * Element#clone(@element, deep) -> Element
+ * - deep (Boolean): Whether to clone `element`'s descendants as well.
+ *
+ * Returns a duplicate of `element`.
+ *
+ * A wrapper around DOM Level 2 `Node#cloneNode`, `Element#clone` cleans up
+ * any expando properties defined by Prototype.
+ **/
+ clone: function(element, deep) {
+ if (!(element = $(element))) return;
+ var clone = element.cloneNode(deep);
+ clone._prototypeUID = void 0;
+ if (deep) {
+ var descendants = Element.select(clone, '*'),
+ i = descendants.length;
+ while (i--) {
+ descendants[i]._prototypeUID = void 0;
+ }
+ }
+ return Element.extend(clone);
}
});
diff --git a/src/dom/event.js b/src/dom/event.js
index 941d941..5e56184 100644
--- a/src/dom/event.js
+++ b/src/dom/event.js
@@ -2,6 +2,34 @@
/** section: DOM
* Event
+ *
+ * The namespace for Prototype's event system.
+ *
+ * Events: a fine mess
+ *
+ * Event management is one of the really sore spots of cross-browser
+ * scripting.
+ *
+ * True, the prevalent issue is: everybody does it the W3C way, and MSIE
+ * does it another way altogether. But there are quite a few subtler,
+ * sneakier issues here and there waiting to bite your ankle — such as the
+ * `keypress`/`keydown` issue with KHTML-based browsers (Konqueror and
+ * Safari). Also, MSIE has a tendency to leak memory when it comes to
+ * discarding event handlers.
+ *
+ * Prototype to the rescue
+ *
+ * Of course, Prototype smooths it over so well you’ll forget these
+ * troubles even exist. Enter the `Event` namespace. It is replete with
+ * methods that help to normalize the information reported by events across
+ * browsers.
+ *
+ * `Event` also provides a standardized list of key codes you can use with
+ * keyboard-related events.
+ *
+ * The functions you’re most likely to use a lot are [[Event.observe]],
+ * [[Event#element]] and [[Event#stop]]. If your web app uses custom events,
+ * you'll also get a lot of mileage out of [[Event.fire]].
**/
var Event = {
KEY_BACKSPACE: 8,
@@ -510,18 +538,21 @@
});
Element.addMethods({
- /** alias of: Event.fire
+ /**
* Element#fire(@element, eventName[, memo[, bubble = true]]) -> Event
+ * See [[Event.fire]].
**/
fire: fire,
- /** alias of: Event.observe
+ /**
* Element#observe(@element, eventName, handler) -> Element
+ * See [[Event.observe]].
**/
observe: observe,
- /** alias of: Event.observe
+ /**
* Element#stopObserving(element[, eventName[, handler]]) -> Element
+ * See [[Event.stopObserving]].
**/
stopObserving: stopObserving
});
@@ -535,16 +566,19 @@
Object.extend(document, {
/**
* document.fire(eventName[, memo[, bubble = true]]) -> Event
+ * See [[Event.fire]].
**/
fire: fire.methodize(),
/**
* document.observe(eventName, handler) -> Element
+ * See [[Event.observe]].
**/
observe: observe.methodize(),
/**
* document.stopObserving([eventName[, handler]]) -> Element
+ * See [[Event.stopObserving]].
**/
stopObserving: stopObserving.methodize(),
diff --git a/src/dom/form.js b/src/dom/form.js
index ed03704..e398374 100644
--- a/src/dom/form.js
+++ b/src/dom/form.js
@@ -1,5 +1,14 @@
/** section: DOM
* Form
+ *
+ * Utilities for dealing with forms in the DOM.
+ *
+ * `Form` is a namespace for all things form-related, packed with form
+ * manipulation and serialization goodness. While it holds methods dealing
+ * with forms as a whole, its submodule [[Form.Element]] deals with specific
+ * form controls.
+ *
+ * Many of these methods are also available directly on `form` elements.
**/
var Form = {
@@ -197,6 +206,22 @@ Form.Methods = {
/** section: DOM
* Form.Element
+ *
+ * Utilities for dealing with form controls in the DOM.
+ *
+ * This is a collection of methods that assist in dealing with form controls.
+ * They provide ways to focus, serialize, disable/enable or extract current
+ * value from a specific control.
+ *
+ * Note that nearly all these methods are available directly on `input`,
+ * `select`, and `textarea` elements. Therefore, these are equivalent:
+ *
+ * Form.Element.activate('myfield');
+ * $('myfield').activate();
+ *
+ * Naturally, you should always prefer the shortest form suitable in a
+ * situation. Most of these methods also return the element itself (as
+ * indicated by the return type) for chainability.
**/
Form.Element = {
diff --git a/src/lang/array.js b/src/lang/array.js
index 62f5f4d..9fc4e05 100644
--- a/src/lang/array.js
+++ b/src/lang/array.js
@@ -1,4 +1,4 @@
-/** section: Language, alias of: Array.from, related to: Array
+/** section: Language, related to: Array
* $A(iterable) -> Array
*
* Accepts an array-like collection (anything with numeric indices) and returns
@@ -168,7 +168,7 @@ Array.from = $A;
* Array#flatten() -> Array
* Returns a “flat” (one-dimensional) version of the array.
*
- * Nested arrays are recursively injected “inline”. This can prove very
+ * Nested arrays are recursively injected "inline." This can prove very
* useful when handling the results of a recursive collection algorithm,
* for instance.
**/
@@ -243,8 +243,12 @@ Array.from = $A;
return array.detect(function(value) { return item === value });
});
}
+
+ /** alias of: Array#clone
+ * Array#toArray() -> Array
+ **/
- /** alias of: Array#toArray
+ /**
* Array#clone() -> Array
*
* Returns a duplicate of the array, leaving the original array intact.
diff --git a/src/lang/class.js b/src/lang/class.js
index 2c6f7be..c399fdc 100644
--- a/src/lang/class.js
+++ b/src/lang/class.js
@@ -2,6 +2,11 @@
/** section: Language
* Class
+ *
+ * Manages Prototype's class-based OOP system.
+ *
+ * Refer to Prototype's web site for a [tutorial on classes and
+ * inheritance](http://prototypejs.org/learn/class-inheritance).
**/
var Class = (function() {
/**
diff --git a/src/lang/enumerable.js b/src/lang/enumerable.js
index 53d25fc..3ba4241 100644
--- a/src/lang/enumerable.js
+++ b/src/lang/enumerable.js
@@ -10,7 +10,7 @@
*
* Prototype mixes `Enumerable` into several classes. The most visible cases
* are [[Array]] and [[Hash]], but you’ll find it in less obvious spots as
- * well, such as in [[ObjectRange]] and various DOM- or AJAX-related objects.
+ * well, such as in [[ObjectRange]] and various DOM- or Ajax-related objects.
*
* The context parameter
*
diff --git a/src/lang/function.js b/src/lang/function.js
index 66a8289..e6f3873 100644
--- a/src/lang/function.js
+++ b/src/lang/function.js
@@ -1,5 +1,7 @@
/** section: Language
* class Function
+ *
+ * Extensions to the built-in `Function` object.
**/
Object.extend(Function.prototype, (function() {
var slice = Array.prototype.slice;
diff --git a/src/lang/range.js b/src/lang/range.js
index 8affa84..70ab2dc 100644
--- a/src/lang/range.js
+++ b/src/lang/range.js
@@ -1,9 +1,10 @@
/** section: Language
* class ObjectRange
*
- * Ranges represent an interval of values. The value type just needs to be
- * "compatible" — that is, to implement a `succ` method letting us step from
- * one value to the next (its successor).
+ * A succession of values.
+ *
+ * An `ObjectRange` can model a range of any value that implements a `succ`
+ * method (which links that value to its "successor").
*
* Prototype provides such a method for [[Number]] and [[String]], but you
* are (of course) welcome to implement useful semantics in your own objects,