From deeb3bbd889886a6b1be96df35d440bee4ea6cd8 Mon Sep 17 00:00:00 2001 From: Andrew Dupont Date: Fri, 20 Mar 2009 05:46:53 -0500 Subject: [PATCH] PDoc changes. --- src/ajax/periodical_updater.js | 15 ++++++++++++- src/ajax/request.js | 6 ++--- src/ajax/updater.js | 6 ++--- src/dom/dom.js | 23 +++++++++++++++++++ src/dom/event.js | 40 +++++++++++++++++++++++++++++++--- src/dom/form.js | 25 +++++++++++++++++++++ src/lang/array.js | 10 ++++++--- src/lang/class.js | 5 +++++ src/lang/enumerable.js | 2 +- src/lang/function.js | 2 ++ src/lang/range.js | 7 +++--- 11 files changed, 124 insertions(+), 17 deletions(-) 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,