From 29b81fda6940a0966339798ff650b1c534c5f1c8 Mon Sep 17 00:00:00 2001 From: tjcrowder Date: Thu, 10 Sep 2009 10:31:56 +0100 Subject: [PATCH 01/34] doc: Merged old docs for Function#argumentNames. --- src/lang/function.js | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/src/lang/function.js b/src/lang/function.js index f535766..9aec762 100644 --- a/src/lang/function.js +++ b/src/lang/function.js @@ -23,6 +23,17 @@ Object.extend(Function.prototype, (function() { * Reads the argument names as stated in the function definition and returns * the values as an array of strings (or an empty array if the function is * defined without parameters). + * + * ### Examples + * + * function fn(foo, bar) { + * return foo + bar; + * } + * fn.argumentNames(); + * //-> ['foo', 'bar'] + * + * Prototype.emptyFunction.argumentNames(); + * //-> [] **/ function argumentNames() { var names = this.toString().match(/^[\s\(]*function[^(]*\(([^)]*)\)/)[1] From 853e0fbbec2473aa75a63410c1f2f98e3c0bcf76 Mon Sep 17 00:00:00 2001 From: tjcrowder Date: Thu, 10 Sep 2009 11:33:11 +0100 Subject: [PATCH 02/34] doc: Update Function#bind documentation, adding examples (simpler, less rambling ones than the old docs). --- src/lang/function.js | 66 ++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 61 insertions(+), 5 deletions(-) diff --git a/src/lang/function.js b/src/lang/function.js index 9aec762..7dd5107 100644 --- a/src/lang/function.js +++ b/src/lang/function.js @@ -42,12 +42,68 @@ Object.extend(Function.prototype, (function() { return names.length == 1 && !names[0] ? [] : names; } - /** - * Function#bind(object[, args...]) -> Function - * - object (Object): The object to bind to. + /** related to: Function#bindAsEventListener + * Function#bind(context[, args...]) -> Function + * - context (Object): The object to bind to. + * - args (?): Optional additional arguments to curry for the function. * - * Wraps the function in another, locking its execution scope to an object - * specified by `object`. + * Binds this function to the given `context` by wrapping it in another + * function and returning the wrapper. Whenever the resulting "bound" + * function is called, it will call the original ensuring that `this` is set + * to `context`. Also optionally curries arguments for the function. + * + * ### Examples + * + * A typical use of `Function#bind` is to ensure that a callback (event + * handler, etc.) that is an object method gets called with the correct + * object as its context (`this` value): + * + * var AlertOnClick = Class.create({ + * initialize: function(msg) { + * this.msg = msg; + * }, + * handleClick: function(event) { + * event.stop(); + * alert(this.msg); + * } + * }); + * var myalert = new AlertOnClick("Clicked!"); + * $('foo').observe('click', myalert.handleClick); // <= WRONG + * // -> If 'foo' is clicked, the alert will be blank; "this" is wrong + * $('bar').observe('click', myalert.handleClick.bind(myalert)); // <= RIGHT + * // -> If 'bar' is clicked, the alert will be "Clicked!" + * + * `bind` can also *curry* (burn in) arguments for the function if you + * provide them after the `context` argument: + * + * var Averager = Class.create({ + * initialize: function() { + * this.count = 0; + * this.total = 0; + * }, + * add: function(addend) { + * ++this.count; + * this.total += addend; + * }, + * getAverage: function() { + * return this.count == 0 ? NaN : this.total / this.count; + * } + * }); + * var a = new Averager(); + * var b = new Averager(); + * var aAdd5 = a.add.bind(a, 5); // Bind to a, curry 5 + * var aAdd10 = a.add.bind(a, 10); // Bind to a, curry 10 + * var bAdd20 = b.add.bind(b, 20); // Bind to b, curry 20 + * aAdd5(); + * aAdd10(); + * bAdd20(); + * bAdd20(); + * alert(a.getAverage()); + * // -> Alerts "7.5" (average of [5, 10]) + * alert(b.getAverage()); + * // -> Alerts "20" (average of [20, 20]) + * + * (To curry without binding, see [[Function#curry]].) **/ function bind(context) { if (arguments.length < 2 && Object.isUndefined(arguments[0])) return this; From c7d0bcdb6c2934ff4be20ef8dc74ee2cb198a02f Mon Sep 17 00:00:00 2001 From: tjcrowder Date: Thu, 10 Sep 2009 12:53:30 +0100 Subject: [PATCH 03/34] doc: Fleshed out docs on Function#bindAsEventListener and added new example. --- src/lang/function.js | 51 ++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 49 insertions(+), 2 deletions(-) diff --git a/src/lang/function.js b/src/lang/function.js index 7dd5107..45e8182 100644 --- a/src/lang/function.js +++ b/src/lang/function.js @@ -115,12 +115,59 @@ Object.extend(Function.prototype, (function() { } /** related to: Function#bind - * Function#bindAsEventListener(object[, args...]) -> Function - * - object (Object): The object to bind to. + * Function#bindAsEventListener(context[, args...]) -> Function + * - context (Object): The object to bind to. + * - args (?): Optional arguments to curry after the event argument. * * An event-specific variant of [[Function#bind]] which ensures the function * will recieve the current event object as the first argument when * executing. + * + * It is not necessary to use `bindAsEventListener` for all bound event + * handlers; [[Function#bind]] works well for the vast majority of cases. + * `bindAsEventListener` is only needed when: + * + * - Using old-style DOM0 handlers rather than handlers hooked up via + * [[Event.observe]], because `bindAsEventListener` gets the event object + * from the right place (even on MSIE). (If you're using `Event.observe`, + * that's already handled.) + * - You want to bind an event handler and curry additional arguments but + * have those arguments appear after, rather than before, the event object. + * This mostly happens if the number of arguments will vary, and so you + * want to know the event object is the first argument. + * + * ### Example + * + * var ContentUpdater = Class.create({ + * initialize: function(initialData) { + * this.data = Object.extend({}, initialData); + * }, + * // On an event, update the content in the elements whose + * // IDs are passed as arguments from our data + * updateTheseHandler: function(event) { + * var argIndex, id, element; + * event.stop(); + * for (argIndex = 1; argIndex < arguments.length; ++argIndex) { + * id = arguments[argIndex]; + * element = $(id); + * if (element) { + * element.update(String(this.data[id]).escapeHTML()); + * } + * } + * } + * }); + * var cu = new ContentUpdater({ + * dispName: 'Joe Bloggs', + * dispTitle: 'Manager ', + * dispAge: 47 + * }); + * // Using bindAsEventListener because of the variable arg lists: + * $('btnUpdateName').observe('click', + * cu.updateTheseHandler.bindAsEventListener(cu, 'dispName') + * ); + * $('btnUpdateAll').observe('click', + * cu.updateTheseHandler.bindAsEventListener(cu, 'dispName', 'dispTitle', 'dispAge') + * ); **/ function bindAsEventListener(context) { var __method = this, args = slice.call(arguments, 1); From 5f02032763187c2a70151faf424bb473004e2ef6 Mon Sep 17 00:00:00 2001 From: tjcrowder Date: Thu, 10 Sep 2009 13:06:31 +0100 Subject: [PATCH 04/34] doc: Fleshed out docs on Function#curry. --- src/lang/function.js | 25 ++++++++++++++++++++----- 1 file changed, 20 insertions(+), 5 deletions(-) diff --git a/src/lang/function.js b/src/lang/function.js index 45e8182..b8b6acb 100644 --- a/src/lang/function.js +++ b/src/lang/function.js @@ -179,12 +179,27 @@ Object.extend(Function.prototype, (function() { /** * Function#curry(args...) -> Function - * Partially applies the function, returning a function with one or more - * arguments already "filled in." + * - args (?): The arguments to curry. * - * Function#curry works just like [[Function#bind]] without the initial - * scope argument. Use the latter if you need to partially apply a function - * _and_ modify its execution scope at the same time. + * *Curries* (burns in) arguments to a function, returning a new function + * that when called with call the original passing in the curried arguments + * (along with any new ones): + * + * function showArguments() { + * alert($A(arguments).join(', ')); + * } + * showArguments(1, 2,, 3); + * // -> alerts "1, 2, 3" + * + * var f = showArguments.curry(1, 2, 3); + * f('a', 'b'); + * // -> alerts "1, 2, 3, a, b" + * + * `Function#curry` works just like [[Function#bind]] without the initial + * context argument. Use `bind` if you need to curry arguments _and_ set + * context at the same time. + * + * The name "curry" comes from [mathematics](http://en.wikipedia.org/wiki/Currying). **/ function curry() { if (!arguments.length) return this; From d4aa3b7b4aa2821f849d74aec40d2f84e2e78869 Mon Sep 17 00:00:00 2001 From: tjcrowder Date: Thu, 10 Sep 2009 13:11:30 +0100 Subject: [PATCH 05/34] doc: Fleshed out docs on Function#defer. --- src/lang/function.js | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/src/lang/function.js b/src/lang/function.js index b8b6acb..c8ad45f 100644 --- a/src/lang/function.js +++ b/src/lang/function.js @@ -233,6 +233,8 @@ Object.extend(Function.prototype, (function() { /** * Function#defer(args...) -> Number + * - args (?): Optional arguments to pass into the function. + * * Schedules the function to run as soon as the interpreter is idle. * * A "deferred" function will not run immediately; rather, it will run as soon @@ -241,6 +243,18 @@ Object.extend(Function.prototype, (function() { * Behaves much like `window.setTimeout` with a delay set to `0`. Returns an * ID that can be used to clear the timeout with `window.clearTimeout` before * it runs. + * + * ### Example + * + * function showMsg(msg) { + * alert(msg); + * } + * + * showMsg("One"); + * showMsg.defer("Two"); + * showMsg("Three"); + * // Alerts "One", then "Three", then (after a brief pause) "Two" + * // Note that "Three" happens before "Two" **/ function defer() { var args = update([0.01], arguments); From 9300bd0350759c71643b2638dd527c02af367233 Mon Sep 17 00:00:00 2001 From: tjcrowder Date: Thu, 10 Sep 2009 13:15:30 +0100 Subject: [PATCH 06/34] doc: Fleshed out docs on Function#delay. --- src/lang/function.js | 19 +++++++++++++++---- 1 file changed, 15 insertions(+), 4 deletions(-) diff --git a/src/lang/function.js b/src/lang/function.js index c8ad45f..05464ca 100644 --- a/src/lang/function.js +++ b/src/lang/function.js @@ -211,17 +211,28 @@ Object.extend(Function.prototype, (function() { } /** - * Function#delay(seconds[, args...]) -> Number - * - seconds (Number): How long to wait before calling the function. + * Function#delay(timeout[, args...]) -> Number + * - timeout (Number): The time, in seconds, to wait before calling the + * function. + * - args (?): Optional arguments to pass to the function when calling it. * * Schedules the function to run after the specified amount of time, passing * any arguments given. * - * Behaves much like `window.setTimeout`. Returns an integer ID that can be - * used to clear the timeout with `window.clearTimeout` before it runs. + * Behaves much like `window.setTimeout`, but the timeout is in seconds + * rather than milliseconds. Returns an integer ID that can be used to + * clear the timeout with `window.clearTimeout` before it runs. * * To schedule a function to run as soon as the interpreter is idle, use * [[Function#defer]]. + * + * ### Example + * + * function showMsg(msg) { + * alert(msg); + * } + * showMsg.delay(0.1, "Hi there!"); + * // -> Waits a 10th of a second, then alerts "Hi there!" **/ function delay(timeout) { var __method = this, args = slice.call(arguments, 1); From 037a47d68afaae00c97f48b1c4a0b1d1ca24e299 Mon Sep 17 00:00:00 2001 From: tjcrowder Date: Thu, 10 Sep 2009 13:15:46 +0100 Subject: [PATCH 07/34] Added missing semicolon in Function#delay. --- src/lang/function.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/lang/function.js b/src/lang/function.js index 05464ca..6a09f08 100644 --- a/src/lang/function.js +++ b/src/lang/function.js @@ -236,7 +236,7 @@ Object.extend(Function.prototype, (function() { **/ function delay(timeout) { var __method = this, args = slice.call(arguments, 1); - timeout = timeout * 1000 + timeout = timeout * 1000; return window.setTimeout(function() { return __method.apply(__method, args); }, timeout); From d44175277854a4b6188b148f52b552797f2214aa Mon Sep 17 00:00:00 2001 From: tjcrowder Date: Thu, 10 Sep 2009 13:29:27 +0100 Subject: [PATCH 08/34] doc: Merged and updated old docs for Function#methodize. --- src/lang/function.js | 47 +++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 44 insertions(+), 3 deletions(-) diff --git a/src/lang/function.js b/src/lang/function.js index 6a09f08..3e3c485 100644 --- a/src/lang/function.js +++ b/src/lang/function.js @@ -293,10 +293,51 @@ Object.extend(Function.prototype, (function() { /** * Function#methodize() -> Function - * Wraps the function inside another function that, at call time, pushes - * `this` to the original function as the first argument. * - * Used to define both a generic method and an instance method. + * Wraps the function inside another function that, when called, pushes + * `this` to the original function as the first argument (with any further + * arguments following it). + * + * The `methodize` method transforms the original function that has an + * explicit first argument to a function that passes `this` (the current + * context) as an implicit first argument at call time. It is useful when we + * want to transform a function that takes an object to a method of that + * object or its prototype, shortening its signature by one argument. + * + * ### Example + * + * // A function that sets a name on a target object + * function setName(target, name) { + * target.name = name; + * } + * + * // Use it + * obj = {}; + * setName(obj, 'Fred'); + * obj.name; + * // -> "Fred" + * + * // Make it a method of the object + * obj.setName = setName.methodize(); + * + * // Use the method instead + * obj.setName('Barney'); + * obj.name; + * // -> "Barney" + * + * The example above is quite simplistic. It's more useful to copy methodized + * functions to object prototypes so that new methods are immediately shared + * among instances. In the Prototype library, `methodize` is used in various + * places such as the DOM module, so that (for instance) you can hide an + * element either by calling the static version of `Element.hide` and passing in + * an element reference or ID, like so: + * + * Element.hide('myElement'); + * + * ...or if you already have an element reference, just calling the + * methodized form instead: + * + * myElement.hide(); **/ function methodize() { if (this._methodized) return this._methodized; From cdaaaa6421e9c4fa63334a37b28de4fc1ac38bf8 Mon Sep 17 00:00:00 2001 From: tjcrowder Date: Thu, 10 Sep 2009 13:43:01 +0100 Subject: [PATCH 09/34] doc: Merged old docs for Function#wrap, expanded on the signature of the wrapper. --- src/lang/function.js | 31 ++++++++++++++++++++++++++++++- 1 file changed, 30 insertions(+), 1 deletion(-) diff --git a/src/lang/function.js b/src/lang/function.js index 3e3c485..91ce67c 100644 --- a/src/lang/function.js +++ b/src/lang/function.js @@ -274,7 +274,7 @@ Object.extend(Function.prototype, (function() { /** * Function#wrap(wrapperFunction) -> Function - * - wrapperFunction (Function): The function to act as a wrapper. + * - wrapperFunction (Function): The function to use as a wrapper. * * Returns a function "wrapped" around the original function. * @@ -282,6 +282,35 @@ Object.extend(Function.prototype, (function() { * a single method, letting you easily build on existing functions by * specifying before and after behavior, transforming the return value, or * even preventing the original function from being called. + * + * The wraper function is called with this signature: + * + * function wrapperFunction(callOriginal[, args...]) + * + * ...where `callOriginal` is a function that can be used to call the + * original (wrapped) function (or not, as appropriate). (`callOriginal` is + * not a direct reference to the original function, there's a layer of + * indirection in-between that sets up the proper context \[`this` value\] for + * it.) + * + * ### Example + * + * // Wrap String#capitalize so it accepts an additional argument + * String.prototype.capitalize = String.prototype.capitalize.wrap( + * function(callOriginal, eachWord) { + * if (eachWord && this.include(" ")) { + * // capitalize each word in the string + * return this.split(" ").invoke("capitalize").join(" "); + * } else { + * // proceed using the original function + * return callOriginal(); + * } + * }); + * + * "hello world".capitalize(); + * // -> "Hello world" (only the 'H' is capitalized) + * "hello world".capitalize(true); + * // -> "Hello World" (both 'H' and 'W' are capitalized) **/ function wrap(wrapper) { var __method = this; From 4905d1777c61f04f7c9dc53708e5c10df8d88ecb Mon Sep 17 00:00:00 2001 From: tjcrowder Date: Thu, 10 Sep 2009 14:03:07 +0100 Subject: [PATCH 10/34] doc: Fixed name of argument in Function#wrap docs. --- src/lang/function.js | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/lang/function.js b/src/lang/function.js index 91ce67c..3044451 100644 --- a/src/lang/function.js +++ b/src/lang/function.js @@ -273,8 +273,8 @@ Object.extend(Function.prototype, (function() { } /** - * Function#wrap(wrapperFunction) -> Function - * - wrapperFunction (Function): The function to use as a wrapper. + * Function#wrap(wrapper) -> Function + * - wrapper (Function): The function to use as a wrapper. * * Returns a function "wrapped" around the original function. * @@ -285,7 +285,7 @@ Object.extend(Function.prototype, (function() { * * The wraper function is called with this signature: * - * function wrapperFunction(callOriginal[, args...]) + * function wrapper(callOriginal[, args...]) * * ...where `callOriginal` is a function that can be used to call the * original (wrapped) function (or not, as appropriate). (`callOriginal` is From 1bab56cfb7e60119bae3205f3a2b3b8fb5de1c87 Mon Sep 17 00:00:00 2001 From: tjcrowder Date: Thu, 10 Sep 2009 14:04:27 +0100 Subject: [PATCH 11/34] doc: Corrected and new Hash docs, they were describe the 1.5 behavior of not cloning. --- src/lang/hash.js | 17 +++++++---------- 1 file changed, 7 insertions(+), 10 deletions(-) diff --git a/src/lang/hash.js b/src/lang/hash.js index 342c9b9..753f882 100644 --- a/src/lang/hash.js +++ b/src/lang/hash.js @@ -1,11 +1,9 @@ /** section: Language, related to: Hash * $H([object]) -> Hash * - * Creates a `Hash`. - * - * `$H` is a convenience wrapper around the Hash constructor, with a safeguard - * that lets you pass an existing Hash object and get it back untouched - * (instead of uselessly cloning it). + * Creates a `Hash`. This is purely a convenience wrapper around the Hash + * constructor, it does not do anything other than pass any argument it's + * given into the Hash constructor and return the result. **/ function $H(object) { return new Hash(object); @@ -26,11 +24,10 @@ function $H(object) { * *

Creating a hash

* - * There are two ways to construct a Hash instance: the first is regular - * JavaScript object instantiation with the `new` keyword, and the second is - * using the [[$H]] function. There is one difference between them: if a `Hash` - * is passed to `$H`, it will be returned as-is, wherease the same hash passed - * to `new Hash` will be _cloned_ instead. + * You can create a Hash either via `new Hash()` or the convenience alias + * `$H()`; there is **no** difference between them. In either case, you may + * optionally pass in an object to seed the `Hash`. If you pass in a `Hash`, + * it will be cloned. * **/ var Hash = Class.create(Enumerable, (function() { From f457097afa1520b5360a92a22d5ff2bafd4b34b8 Mon Sep 17 00:00:00 2001 From: tjcrowder Date: Thu, 10 Sep 2009 14:13:28 +0100 Subject: [PATCH 12/34] doc: Minor grammar update to Hash#clone. --- src/lang/hash.js | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/lang/hash.js b/src/lang/hash.js index 753f882..6844692 100644 --- a/src/lang/hash.js +++ b/src/lang/hash.js @@ -172,7 +172,7 @@ var Hash = Class.create(Enumerable, (function() { /** related to: Object.inspect * Hash#inspect() -> String * - * Returns the debug-oriented string representation of the hash. + * Returns the debug-oriented string representation of the Hash. **/ function inspect() { return '# Hash * - * Returns a clone of hash. + * Returns a clone of this Hash. **/ function clone() { return new Hash(this); From 00ebde59a200be67af1a1a8c201852a64eb72b98 Mon Sep 17 00:00:00 2001 From: tjcrowder Date: Thu, 10 Sep 2009 14:55:12 +0100 Subject: [PATCH 13/34] doc: Merged old docs for Hash#each. --- src/lang/hash.js | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/src/lang/hash.js b/src/lang/hash.js index 6844692..4e51108 100644 --- a/src/lang/hash.js +++ b/src/lang/hash.js @@ -41,6 +41,45 @@ var Hash = Class.create(Enumerable, (function() { this._object = Object.isHash(object) ? object.toObject() : Object.clone(object); } + // Docs for #each even though technically it's implemented by Enumerable + /** + * Hash#each(iterator[, context]) -> Hash + * - iterator (Function): A function that expects each item in the `Hash` + * as the first argument and a numerical index as the second. + * - context (Object): The scope in which to call `iterator`. Determines what + * `this` means inside `iterator`. + * + * Iterates over the name/value pairs in the hash. + * + * This is actually just the [[Enumerable#each #each]] method from the + * mixed-in [[Enumerable]] module. It is documented here to describe the + * structure of the elements passed to the iterator and the order of + * iteration. + * + * The iterator's first argument (the "item") is an object with two + * properties: + * + * - `key`: the key name as a `String` + * - `value`: the corresponding value (which may be `undefined`) + * + * The order of iteration is implementation-dependent, as it relies on + * the order of the native `for..in` loop. Although most modern + * implementations exhibit *ordered* behavior, this is not standardized and + * may not always be the case, and so cannot be relied upon. + * + * ### Example + * + * var h = $H({version: 1.6, author: 'The Core Team'}); + * + * h.each(function(pair) { + * alert(pair.key + ' = "' + pair.value + '"'); + * }); + * // Alerts 'version = "1.6"' and 'author = "The Core Team"' + * // -or- + * // Alerts 'author = "The Core Team"' and 'version = "1.6"' + **/ + + // Our _internal_ each function _each(iterator) { for (var key in this._object) { var value = this._object[key], pair = [key, value]; From e02a1cf5c62142a94ae5db1f92ef36c2aaabdfa5 Mon Sep 17 00:00:00 2001 From: tjcrowder Date: Thu, 10 Sep 2009 14:57:10 +0100 Subject: [PATCH 14/34] doc: Merged old docs for Hash#get. --- src/lang/hash.js | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/src/lang/hash.js b/src/lang/hash.js index 4e51108..8f4731f 100644 --- a/src/lang/hash.js +++ b/src/lang/hash.js @@ -101,7 +101,13 @@ var Hash = Class.create(Enumerable, (function() { /** * Hash#get(key) -> value * - * Returns the value of the hash's `key` property. + * Returns the stored value for the given `key`. + * + * ### Examples + * + * var h = new Hash({a: 'apple', b: 'banana', c: 'coconut'}); + * h.get('a'); + * // -> 'apple' **/ function get(key) { // simulating poorly supported hasOwnProperty From 305e79e5d3b261728b313a9d93b32b1b16733982 Mon Sep 17 00:00:00 2001 From: tjcrowder Date: Thu, 10 Sep 2009 15:00:34 +0100 Subject: [PATCH 15/34] doc: Merged old docs for Hash#keys, updated example. --- src/lang/hash.js | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/src/lang/hash.js b/src/lang/hash.js index 8f4731f..6088d18 100644 --- a/src/lang/hash.js +++ b/src/lang/hash.js @@ -138,7 +138,15 @@ var Hash = Class.create(Enumerable, (function() { /** * Hash#keys() -> [String...] * - * Provides an Array of keys (that is, property names) for the hash. + * Provides an Array containing the keys for items stored in the hash. + * + * The order of the keys is not guaranteed. + * + * ### Example + * + * var h = $H({one: "uno", two: "due", three: "tre"}); + * h.keys(); + * // -> ["one", "three", "two] (these may be in any order) **/ function keys() { return this.pluck('key'); From ab5a19a1c1199f4bee60f90d9163af6e906e94f0 Mon Sep 17 00:00:00 2001 From: tjcrowder Date: Thu, 10 Sep 2009 15:07:28 +0100 Subject: [PATCH 16/34] doc: Merged old docs for Hash#merge, updated example. --- src/lang/hash.js | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/src/lang/hash.js b/src/lang/hash.js index 6088d18..26c79fe 100644 --- a/src/lang/hash.js +++ b/src/lang/hash.js @@ -176,10 +176,22 @@ var Hash = Class.create(Enumerable, (function() { /** * Hash#merge(object) -> Hash + * - object (Object | Hash): The object to merge with this hash to produce + * the resulting hash. + * + * Returns a new `Hash` instance with `object`'s key/value pairs merged in; + * this hash remains unchanged. * - * Returns a new hash with `object`'s key/value pairs merged in. * To modify the original hash in place, use [[Hash#update]]. * + * ### Example + * + * var h = $H({one: "uno", two: "due"}); + * var h2 = h.merge({three: "tre"}); + * h.keys(); + * // -> ["one", "two"] (unchanged) + * h2.keys(); + * // -> ["one", "two", "three"] (has merged contents) **/ function merge(object) { return this.clone().update(object); From 62a3c8fb38febc265c303f5b0f6aa0bf986240ff Mon Sep 17 00:00:00 2001 From: tjcrowder Date: Thu, 10 Sep 2009 15:12:56 +0100 Subject: [PATCH 17/34] doc: Merged and updated old docs for Hash#get --- src/lang/hash.js | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/src/lang/hash.js b/src/lang/hash.js index 26c79fe..f0ce359 100644 --- a/src/lang/hash.js +++ b/src/lang/hash.js @@ -91,8 +91,22 @@ var Hash = Class.create(Enumerable, (function() { /** * Hash#set(key, value) -> value + * - key (String): The key to use for this value. + * - value (?): The value to use for this key. * - * Sets the hash's `key` property to `value` and returns `value`. + * Stores `value` in the hash using the key `key` and returns `value`. + * + * ### Example + * + * var h = $H(); + * h.keys(); + * // -> [] (initially empty) + * h.set('a', 'apple'); + * // -> "apple" + * h.keys(); + * // -> ["a"] (has the new entry) + * h.get('a'); + * // -> "apple" **/ function set(key, value) { return this._object[key] = value; From 64cd05dd599b4a6aae4a08a987bad0ed7b429b4b Mon Sep 17 00:00:00 2001 From: tjcrowder Date: Thu, 10 Sep 2009 15:15:36 +0100 Subject: [PATCH 18/34] doc: Fleshed out docs for Hash#toJSON. --- src/lang/hash.js | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/src/lang/hash.js b/src/lang/hash.js index f0ce359..daeb729 100644 --- a/src/lang/hash.js +++ b/src/lang/hash.js @@ -262,7 +262,13 @@ var Hash = Class.create(Enumerable, (function() { /** related to: Object.toJSON * Hash#toJSON() -> String * - * Returns a JSON string. + * Returns a JSON string containing the keys and values in this hash. + * + * ### Example + * + * var h = $H({'a': 'apple', 'b': 23, 'c': false}); + * h.toJSON(); + * // -> {"a": "apple", "b": 23, "c": false} **/ function toJSON() { return Object.toJSON(this.toObject()); From 48a0f5a44cf04d0ae713f7e48b92880eecce260b Mon Sep 17 00:00:00 2001 From: tjcrowder Date: Thu, 10 Sep 2009 15:18:05 +0100 Subject: [PATCH 19/34] doc: Merged and updated old docs for Hash#toObject. --- src/lang/hash.js | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/src/lang/hash.js b/src/lang/hash.js index daeb729..2c40203 100644 --- a/src/lang/hash.js +++ b/src/lang/hash.js @@ -143,7 +143,15 @@ var Hash = Class.create(Enumerable, (function() { /** * Hash#toObject() -> Object * - * Returns a cloned, vanilla object. + * Returns a cloned, vanilla object whose properties (and property values) + * match the keys (and values) from the hash. + * + * ### Example + * + * var h = new Hash({ a: 'apple', b: 'banana', c: 'coconut' }); + * var obj = h.toObject(); + * obj.a; + * // -> "apple" **/ function toObject() { return Object.clone(this._object); From da402268acc5ba334c53b5b20c3ac13e2a2a66ea Mon Sep 17 00:00:00 2001 From: tjcrowder Date: Thu, 10 Sep 2009 15:37:26 +0100 Subject: [PATCH 20/34] doc: Merged and updated old docs for Hash#toQueryString. --- src/lang/hash.js | 36 +++++++++++++++++++++++++++++++++++- 1 file changed, 35 insertions(+), 1 deletion(-) diff --git a/src/lang/hash.js b/src/lang/hash.js index 2c40203..21e2b5f 100644 --- a/src/lang/hash.js +++ b/src/lang/hash.js @@ -242,7 +242,41 @@ var Hash = Class.create(Enumerable, (function() { /** related to: String#toQueryParams * Hash#toQueryString() -> String * - * Turns a hash into its URL-encoded query string representation. + * Returns a URL-encoded string containing the hash's contents as query + * parameters according to the following rules: + * + * - An undefined value results a parameter with no value portion at all + * (simply the key name, no equal sign). + * - A null value results a parameter with a blank value (the key followed + * by an equal sign and nothing else). + * - A boolean value results a parameter with the value "true" or "false". + * - An Array value results in a parameter for each array element, in + * array order, each using the same key. + * - All keys and values are URI-encoded using JavaScript's native + * `encodeURIComponent` function. + * + * The order of pairs in the string is not guaranteed, other than the order + * of array values described above. + * + * ### Example + * + * $H({action: 'ship', + * order_id: 123, + * fees: ['f1', 'f2'] + * }).toQueryString(); + * // -> "action=ship&order_id=123&fees=f1&fees=f2" + * + * $H({comment: '', + * 'key with spaces': true, + * related_order: undefined, + * contents: null, + * 'label': 'a demo' + * }).toQueryString(); + * // -> "comment=&key%20with%20spaces=true&related_order&contents=&label=a%20demo" + * + * // an empty hash is an empty query string: + * $H().toQueryString(); + * // -> "" **/ function toQueryString() { return this.inject([], function(results, pair) { From 71e07f0efa6dbb4fa2d53647b4c28276ffae246d Mon Sep 17 00:00:00 2001 From: tjcrowder Date: Thu, 10 Sep 2009 15:39:34 +0100 Subject: [PATCH 21/34] doc: Merged and updated old docs for Hash#unset. --- src/lang/hash.js | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/src/lang/hash.js b/src/lang/hash.js index 21e2b5f..3f71de7 100644 --- a/src/lang/hash.js +++ b/src/lang/hash.js @@ -132,7 +132,18 @@ var Hash = Class.create(Enumerable, (function() { /** * Hash#unset(key) -> value * - * Deletes the hash's `key` property and returns its value. + * Deletes the stored pair for the given `key` from the hash and returns its + * value. + * + * ### Example + * + * var h = new Hash({a: 'apple', b: 'banana', c: 'coconut'}); + * h.keys(); + * // -> ["a", "b", "c"] + * h.unset('a'); + * // -> 'apple' + * h.keys(); + * // -> ["b", "c"] ("a" is no longer in the hash) **/ function unset(key) { var value = this._object[key]; From 1910e08a79eb6a3cdc0cad86a9b8b2dfce8b8149 Mon Sep 17 00:00:00 2001 From: tjcrowder Date: Thu, 10 Sep 2009 15:42:04 +0100 Subject: [PATCH 22/34] doc: Merged and updated old docs for Hash#update. --- src/lang/hash.js | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/src/lang/hash.js b/src/lang/hash.js index 3f71de7..3f020ea 100644 --- a/src/lang/hash.js +++ b/src/lang/hash.js @@ -232,10 +232,22 @@ var Hash = Class.create(Enumerable, (function() { /** * Hash#update(object) -> Hash + * - object (Object | Hash): The object to merge with this hash to produce + * the resulting hash. * - * Updates hash with the key/value pairs of `object`. - * The original hash will be modified. To return a new hash instead, use + * Updates a hash *in place* with the key/value pairs of `object`, returns + * the hash. + * + * `update` modifies the hash. To get a new hash instead, use * [[Hash#merge]]. + * + * ### Example + * + * var h = $H({one: "uno", two: "due"}); + * h.update({three: "tre"}); + * // -> h (a reference to the original hash) + * h.keys(); + * // -> ["one", "two", "three"] (has merged contents) **/ function update(object) { return new Hash(object).inject(this, function(result, pair) { From 3ee5b5ddd80567ab9fd6335847cab8d3df442c2f Mon Sep 17 00:00:00 2001 From: tjcrowder Date: Thu, 10 Sep 2009 15:43:29 +0100 Subject: [PATCH 23/34] doc: Merged and updated old docs for Hash#values. --- src/lang/hash.js | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/src/lang/hash.js b/src/lang/hash.js index 3f020ea..ec9ab14 100644 --- a/src/lang/hash.js +++ b/src/lang/hash.js @@ -188,7 +188,15 @@ var Hash = Class.create(Enumerable, (function() { /** * Hash#values() -> Array * - * Collect the values of a hash and returns them in an array. + * Collects the values of the hash and returns them in an array. + * + * The order of the values is not guaranteed. + * + * ### Example + * + * var h = $H({one: "uno", two: "due", three: "tre"}); + * h.values(); + * // -> ["uno", "tre", "due"] (these may be in any order) **/ function values() { return this.pluck('value'); From fe5290e15ea2b8cd9c7d710d00baf93aadbc36ba Mon Sep 17 00:00:00 2001 From: tjcrowder Date: Thu, 10 Sep 2009 15:45:05 +0100 Subject: [PATCH 24/34] doc: Fixed missing quote in example for Hash#keys and missing arrows in example for Hash#each. --- src/lang/hash.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/lang/hash.js b/src/lang/hash.js index ec9ab14..801ad90 100644 --- a/src/lang/hash.js +++ b/src/lang/hash.js @@ -179,7 +179,7 @@ var Hash = Class.create(Enumerable, (function() { * * var h = $H({one: "uno", two: "due", three: "tre"}); * h.keys(); - * // -> ["one", "three", "two] (these may be in any order) + * // -> ["one", "three", "two"] (these may be in any order) **/ function keys() { return this.pluck('key'); From 917f10b5740704c2d644855e676753d638b9f95d Mon Sep 17 00:00:00 2001 From: tjcrowder Date: Thu, 10 Sep 2009 16:15:21 +0100 Subject: [PATCH 25/34] doc: Modified Number preamble to leave out unnecessary reference to Ruby. --- src/lang/number.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/lang/number.js b/src/lang/number.js index d97480b..3c4a0aa 100644 --- a/src/lang/number.js +++ b/src/lang/number.js @@ -6,7 +6,7 @@ * Prototype extends native JavaScript numbers in order to provide: * * * [[ObjectRange]] compatibility, through [[Number#succ]]. - * * Ruby-like numerical loops with [[Number#times]]. + * * Numerical loops with [[Number#times]]. * * Simple utility methods such as [[Number#toColorPart]] and * [[Number#toPaddedString]]. * * Instance-method aliases of many functions in the `Math` namespace. From e5fa0928e85af8d8daa1581e3a2a04502758cb2b Mon Sep 17 00:00:00 2001 From: tjcrowder Date: Thu, 10 Sep 2009 16:17:35 +0100 Subject: [PATCH 26/34] doc: Fleshed out Number#abs slightly. --- src/lang/number.js | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/lang/number.js b/src/lang/number.js index 3c4a0aa..6825b84 100644 --- a/src/lang/number.js +++ b/src/lang/number.js @@ -70,7 +70,8 @@ Object.extend(Number.prototype, (function() { /** * Number#abs() -> Number * - * Returns the absolute value of the number. + * Returns the absolute value of the number. Convenience method that simply + * calls `Math.abs` on this instance and returns the result. **/ function abs() { return Math.abs(this); From e05a089b335181737eca73ba62a34ab5c0253c96 Mon Sep 17 00:00:00 2001 From: tjcrowder Date: Thu, 10 Sep 2009 16:18:12 +0100 Subject: [PATCH 27/34] doc: Fleshed out Number#ceil slightly. --- src/lang/number.js | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/lang/number.js b/src/lang/number.js index 6825b84..c7f3781 100644 --- a/src/lang/number.js +++ b/src/lang/number.js @@ -90,6 +90,8 @@ Object.extend(Number.prototype, (function() { * Number#ceil() -> Number * * Returns the smallest integer greater than or equal to the number. + * Convenience method that simply calls `Math.ceil` on this instance and + * returns the result. **/ function ceil() { return Math.ceil(this); From b12ec913d7ee313e78106af9dab5baf5dffa9413 Mon Sep 17 00:00:00 2001 From: tjcrowder Date: Thu, 10 Sep 2009 16:18:33 +0100 Subject: [PATCH 28/34] doc: Fleshed out Number#floor slightly. --- src/lang/number.js | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/lang/number.js b/src/lang/number.js index c7f3781..7f4ef9b 100644 --- a/src/lang/number.js +++ b/src/lang/number.js @@ -101,6 +101,8 @@ Object.extend(Number.prototype, (function() { * Number#floor() -> Number * * Returns the largest integer less than or equal to the number. + * Convenience method that simply calls `Math.floor` on this instance and + * returns the result. **/ function floor() { return Math.floor(this); From 20724ea1f95ec4b927b01ed8ceb45f248d2d5f05 Mon Sep 17 00:00:00 2001 From: tjcrowder Date: Thu, 10 Sep 2009 16:18:59 +0100 Subject: [PATCH 29/34] doc: Fleshed out Number#round slightly. --- src/lang/number.js | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/lang/number.js b/src/lang/number.js index 7f4ef9b..a3bc9b0 100644 --- a/src/lang/number.js +++ b/src/lang/number.js @@ -80,7 +80,8 @@ Object.extend(Number.prototype, (function() { /** * Number#round() -> Number * - * Rounds the number to the nearest integer. + * Rounds the number to the nearest integer. Convenience method that simply + * calls `Math.round` on this instance and returns the result. **/ function round() { return Math.round(this); From e6b6193124b2a1604678674ba4a69789373c9560 Mon Sep 17 00:00:00 2001 From: tjcrowder Date: Thu, 10 Sep 2009 16:30:19 +0100 Subject: [PATCH 30/34] doc: Fleshed out Number#times. --- src/lang/number.js | 28 ++++++++++++++++++++++++---- 1 file changed, 24 insertions(+), 4 deletions(-) diff --git a/src/lang/number.js b/src/lang/number.js index a3bc9b0..bd171a7 100644 --- a/src/lang/number.js +++ b/src/lang/number.js @@ -35,11 +35,31 @@ Object.extend(Number.prototype, (function() { } /** - * Number#times(iterator) -> Number + * Number#times(iterator[,context]) -> Number + * - iterator (Function): An iterator function to call. + * - context (Object): An optional context (`this` value) to use when + * calling `iterator`. * - * Calls `iterator` the specified number of times. - * The function takes an integer as the first parameter; it will start at 0 - * and be incremented after each invocation. + * Calls `iterator` the specified number of times, passing in a number as + * the first parameter. The number will be 0 on first call, 1 on second + * call, etc. `times` returns the number instance it was called on. + * + * ### Example + * + * (3).times(alert); + * // -> Alerts "0", then "1", then "2"; returns 3 + * + * var obj = {count: 0, total: 0}; + * function add(addend) { + * ++this.count; + * this.total += addend; + * } + * (4).times(add, obj); + * // -> 4 + * obj.count; + * // -> 4 + * obj.total; + * // -> 6 (e.g., 0 + 1 + 2 + 3) **/ function times(iterator, context) { $R(0, this, true).each(iterator, context); From a47d9e1c2f5898991784fc3a49f4adbdebf3e5bb Mon Sep 17 00:00:00 2001 From: tjcrowder Date: Thu, 10 Sep 2009 16:32:36 +0100 Subject: [PATCH 31/34] doc: Merged and updated old docs for Number#toColorPart. --- src/lang/number.js | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/src/lang/number.js b/src/lang/number.js index bd171a7..ea7da0d 100644 --- a/src/lang/number.js +++ b/src/lang/number.js @@ -17,8 +17,13 @@ Object.extend(Number.prototype, (function() { * Number#toColorPart() -> String * * Produces a 2-digit hexadecimal representation of the number - * (which is therefore assumed to be in the [0..255] range). + * (which is therefore assumed to be in the \[0..255\] range, inclusive). * Useful for composing CSS color strings. + * + * ### Example + * + * 10.toColorPart() + * // -> "0a" **/ function toColorPart() { return this.toPaddedString(2, 16); From 63ea557b064b7f5fc9660432f3ff7d886e832044 Mon Sep 17 00:00:00 2001 From: tjcrowder Date: Thu, 10 Sep 2009 16:51:36 +0100 Subject: [PATCH 32/34] doc: Merged and updated old docs for Number#toPaddedString. --- src/lang/number.js | 26 +++++++++++++++++++++++--- 1 file changed, 23 insertions(+), 3 deletions(-) diff --git a/src/lang/number.js b/src/lang/number.js index ea7da0d..643d1e9 100644 --- a/src/lang/number.js +++ b/src/lang/number.js @@ -73,10 +73,30 @@ Object.extend(Number.prototype, (function() { /** * Number#toPaddedString(length[, radix]) -> String + * - length (Number): The minimum length for the resulting string. + * - radix (Number): An optional radix for the string representation, + * defaults to 10 (decimal). * - * Converts the number into a string padded with 0s so that the string's length - * is at least equal to `length`. - * Takes an optional `radix` argument which specifies the base to use for conversion. + * Returns a string representation of the number padded with leading 0s so + * that the string's length is at least equal to `length`. Takes an optional + * `radix` argument which specifies the base to use for conversion. + * + * ### Examples + * + * (13).toPaddedString(4); + * // -> "0013" + * + * (13).toPaddedString(2); + * // -> "13" + * + * (13).toPaddedString(1); + * // -> "13" + * + * (13).toPaddedString(4, 16) + * // -> "000d" + * + * (13).toPaddedString(4, 2); + * // -> "1101" **/ function toPaddedString(length, radix) { var string = this.toString(radix || 10); From f4314a878989eb7376f129e1967f7fefb64f0a8b Mon Sep 17 00:00:00 2001 From: tjcrowder Date: Thu, 10 Sep 2009 17:12:38 +0100 Subject: [PATCH 33/34] doc: Merged and updated old docs for Object.clone. --- src/lang/object.js | 26 +++++++++++++++++++++++--- 1 file changed, 23 insertions(+), 3 deletions(-) diff --git a/src/lang/object.js b/src/lang/object.js index e6ac732..6676045 100644 --- a/src/lang/object.js +++ b/src/lang/object.js @@ -167,12 +167,32 @@ * Object.clone(object) -> Object * - object (Object): The object to clone. * - * Duplicates the passed object. - * - * Copies all the original's key/value pairs onto an empty object. + * Creates and returns a shallow duplicate of the passed object by copying + * all of the original's key/value pairs onto an empty object. * * Do note that this is a _shallow_ copy, not a _deep_ copy. Nested objects * will retain their references. + * + * ### Examples + * + * var original = {name: 'primaryColors', values: ['red', 'green', 'blue']}; + * var copy = Object.clone(original); + * original.name; + * // -> "primaryColors" + * original.values[0]; + * // -> "red" + * copy.name; + * // -> "primaryColors" + * copy.name = "secondaryColors"; + * original.name; + * // -> "primaryColors" + * copy.name; + * // -> "secondaryColors" + * copy.values[0] = 'magenta'; + * copy.values[1] = 'cyan'; + * copy.values[2] = 'yellow'; + * original.values[0]; + * // -> "magenta" (it was a shallow copy, so they shared the array) **/ function clone(object) { return extend({ }, object); From cfc7e7a2e74339eae4d091f049ce5a336198bd60 Mon Sep 17 00:00:00 2001 From: tjcrowder Date: Thu, 10 Sep 2009 17:45:11 +0100 Subject: [PATCH 34/34] doc: Convert all subheadings to H5s throughout. --- src/ajax.js | 6 ++--- src/ajax/periodical_updater.js | 4 +-- src/ajax/request.js | 4 +-- src/ajax/responders.js | 2 +- src/ajax/updater.js | 10 ++++---- src/dom/dom.js | 2 +- src/dom/event.js | 24 +++++++++--------- src/dom/form.js | 6 ++--- src/lang/array.js | 24 +++++++++--------- src/lang/class.js | 2 +- src/lang/date.js | 2 +- src/lang/enumerable.js | 46 +++++++++++++++++----------------- src/lang/function.js | 14 +++++------ src/lang/hash.js | 24 +++++++++--------- src/lang/number.js | 6 ++--- src/lang/object.js | 2 +- src/lang/string.js | 10 ++++---- src/lang/template.js | 8 +++--- 18 files changed, 98 insertions(+), 98 deletions(-) diff --git a/src/ajax.js b/src/ajax.js index 3102025..88a1f52 100644 --- a/src/ajax.js +++ b/src/ajax.js @@ -8,7 +8,7 @@ * * Actual requests are made by creating instances of [[Ajax.Request]]. * - *

Request headers

+ *
Request headers
* * The following headers are sent with all Ajax requests (and can be * overridden with the `requestHeaders` option described below): @@ -21,7 +21,7 @@ * * `Content-type` is automatically determined based on the `contentType` * and `encoding` options. * - *

Ajax options

+ *
Ajax options
* * All Ajax classes share a common set of _options_ and _callbacks_. * Callbacks are called at various points in the life-cycle of a request, and @@ -64,7 +64,7 @@ * `true` otherwise): Sanitizes the contents of * [[Ajax.Response#responseText]] before evaluating it. * - *

Common callbacks

+ *
Common callbacks
* * When used on individual instances, all callbacks (except `onException`) are * invoked with two parameters: the `XMLHttpRequest` object and the result of diff --git a/src/ajax/periodical_updater.js b/src/ajax/periodical_updater.js index 3214273..d5fa4ef 100644 --- a/src/ajax/periodical_updater.js +++ b/src/ajax/periodical_updater.js @@ -16,7 +16,7 @@ * keeping track of the response text so it can (optionally) react to * receiving the exact same response consecutively. * - *

Additional options

+ *
Additional options
* * `Ajax.PeriodicalUpdater` features all the common options and callbacks * described in the [[Ajax section]] — _plus_ those added by `Ajax.Updater`. @@ -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 diff --git a/src/ajax/request.js b/src/ajax/request.js index b79df17..352cc48 100644 --- a/src/ajax/request.js +++ b/src/ajax/request.js @@ -5,7 +5,7 @@ * * `Ajax.Request` is a general-purpose class for making HTTP requests. * - *

Automatic JavaScript response evaluation

+ *
Automatic JavaScript response evaluation
* * If an Ajax request follows the _same-origin policy_ **and** its response * has a JavaScript-related `Content-type`, the content of the `responseText` @@ -28,7 +28,7 @@ * * The MIME-type string is examined in a case-insensitive manner. * - *

Methods you may find useful

+ *
Methods you may find useful
* * Instances of the `Request` object provide several methods that can come in * handy in your callback functions, especially once the request is complete. diff --git a/src/ajax/responders.js b/src/ajax/responders.js index 8fe5c26..c9ed244 100644 --- a/src/ajax/responders.js +++ b/src/ajax/responders.js @@ -34,7 +34,7 @@ * } * }); * - *

Responder callbacks

+ *
Responder callbacks
* * The callbacks for responders are similar to the callbacks described in * the [[Ajax section]], but take a different signature. They're invoked with diff --git a/src/ajax/updater.js b/src/ajax/updater.js index 6979dfa..7cb23da 100644 --- a/src/ajax/updater.js +++ b/src/ajax/updater.js @@ -7,7 +7,7 @@ * `Ajax.Updater` is a subclass of [[Ajax.Request]] built for a common * use-case. * - *

Example

+ *
Example
* * new Ajax.Updater('items', '/items', { * parameters: { text: $F('text') } @@ -17,13 +17,13 @@ * parameters); it will then replace the contents of the element with the ID * of `items` with whatever response it receives. * - *

Callbacks

+ *
Callbacks
* * `Ajax.Updater` supports all the callbacks listed in the [[Ajax section]]. * Note that the `onComplete` callback will be invoked **after** the element * is updated. * - *

Additional options

+ *
Additional options
* * `Ajax.Updater` has some options of its own apart from the common options * described in the [[Ajax section]]: @@ -37,7 +37,7 @@ * `top`, `bottom`, `before`, or `after` — and _inserts_ the contents of the * response in the manner described by [[Element#insert]]. * - *

More About `evalScripts`

+ *
More About `evalScripts`
* * If you use `evalScripts: true`, any _inline_ `End of test

".stripScripts(); * // => "

This is a test.End of test

" * - *

Caveat User

+ *
Caveat User
* * Note that the processing `stripScripts` does is good enough for most purposes, * but you cannot rely on it for security purposes. If you're processing end-user-supplied @@ -183,7 +183,7 @@ Object.extend(String.prototype, (function() { * they were empty (the result for that position in the array will be `undefined`); * external files are _not_ loaded and processed by `evalScripts`. * - *

About `evalScripts`, `var`s, and defining functions

+ *
About `evalScripts`, `var`s, and defining functions
* * `evalScripts` evaluates script blocks, but this **does not** mean they are * evaluated in the global scope. They aren't, they're evaluated in the scope of @@ -302,7 +302,7 @@ Object.extend(String.prototype, (function() { * Converts a string separated by dashes into a camelCase equivalent. * For instance, 'foo-bar' would be converted to 'fooBar'. * - *

Examples

+ *
Examples
* * 'background-color'.camelize(); * // -> 'backgroundColor' diff --git a/src/lang/template.js b/src/lang/template.js index 435a3e7..cb9020d 100644 --- a/src/lang/template.js +++ b/src/lang/template.js @@ -14,7 +14,7 @@ * expression. The `Template` class provides a much nicer and clearer way of * achieving this formatting. * - *

Straightforward templates

+ *
Straightforward templates
* * The `Template` class uses a basic formatting syntax, similar to what is * used in Ruby. The templates are created from strings that have embedded @@ -36,7 +36,7 @@ * myTemplate.evaluate(show); * // -> "The TV show The Simpsons was created by Matt Groening." * - *

Templates are meant to be reused

+ *
Templates are meant to be reused
* * As the example illustrates, `Template` objects are not tied to specific * data. The data is bound to the template only during the evaluation of the @@ -60,7 +60,7 @@ * // -> Multiply by 0.9478 to convert from kilojoules to BTUs. * // -> Multiply by 1024 to convert from megabytes to gigabytes. * - *

Escape sequence

+ *
Escape sequence
* * There's always the chance that one day you'll need to have a literal in your * template that looks like a symbol, but is not supposed to be replaced. For @@ -75,7 +75,7 @@ * t.evaluate(data); * // -> in Ruby we also use the #{variable} syntax for templates. * - *

Custom syntaxes

+ *
Custom syntaxes
* * The default syntax of the template strings will probably be enough for most * scenarios. In the rare occasion where the default Ruby-like syntax is