From d189f809a43d22af6aa7e5be2169d61a3042dee7 Mon Sep 17 00:00:00 2001 From: Andrew Dupont Date: Fri, 6 Mar 2009 12:20:09 -0600 Subject: [PATCH] Fixed aliases in PDoc for Enumerable. --- src/lang/enumerable.js | 124 ++++++++++++++++++++++++++++++++++++++--- 1 file changed, 117 insertions(+), 7 deletions(-) diff --git a/src/lang/enumerable.js b/src/lang/enumerable.js index f9f967a..53d25fc 100644 --- a/src/lang/enumerable.js +++ b/src/lang/enumerable.js @@ -1,5 +1,84 @@ /** section: Language * mixin Enumerable + * + * `Enumerable` provides a large set of useful methods for enumerations — + * objects that act as collections of values. It is a cornerstone of + * Prototype. + * + * `Enumerable` is a _mixin_: a set of methods intended not for standaone + * use, but for incorporation into other objects. + * + * 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. + * + *

The context parameter

+ * + * Every method of `Enumerable` that takes an iterator also takes the "context + * object" as the next (optional) parameter. The context object is what the + * iterator will be _bound_ to — what the keyword `this` will refer to inside + * the iterator. + * + * var myObject = {}; + * + * ['foo', 'bar', 'baz'].each(function(name, index) { + * this[name] = index; + * }, myObject); // we have specified the context + * + * myObject + * //-> { foo: 0, bar: 1, baz: 2} + * + * If there is no `context` argument, the iterator function will execute in + * the scope from which the `Enumerable` method itself was called. + * + *

Mixing Enumerable into your own objects

+ * + * So, let’s say you’ve created your very own collection-like object (say, + * some sort of Set, or perhaps something that dynamically fetches data + * ranges from the server side, lazy-loading style). You want to be able to + * mix `Enumerable` in (and we commend you for it). How do you go about this? + * + * The Enumerable module basically makes only one requirement on your object: + * it must provide a method named `_each` (note the leading underscore) that + * will accept a function as its unique argument, and will contain the actual + * “raw iteration” algorithm, invoking its argument with each element in turn. + * + * As detailed in the documentation for [[Enumerable#each]], `Enumerable` + * provides all the extra layers (handling iteration short-circuits, passing + * numeric indices, etc.). You just need to implement the actual iteration, + * as fits your internal structure. + * + * If you're still confused, just have a look at the Prototype source code for + * [[Array]], [[Hash]], or [[ObjectRange]]. They all begin with their own + * `_each` method, which should help you grasp the idea. + * + * Once you’re done with this, you just need to mix `Enumerable` in, which + * you’ll usually do before defining your methods, so as to make sure whatever + * overrides you provide for `Enumerable` methods will indeed prevail. In + * short, your code will probably end up looking like this: + * + * + * var YourObject = Class.create(Enumerable, { + * initialize: function() { // with whatever constructor arguments you need + * // Your construction code + * }, + * + * _each: function(iterator) { + * // Your iteration code, invoking iterator at every turn + * }, + * + * // Your other methods here, including Enumerable overrides + * }); + * + * Then, obviously, your object can be used like this: + * + * var obj = new YourObject(); + * // Populate the collection somehow + * obj.pluck('somePropName'); + * obj.invoke('someMethodName'); + * obj.size(); + * // etc. + * **/ var $break = { }; @@ -74,7 +153,7 @@ var Enumerable = (function() { return result; } - /** alias of: Enumerable#map + /** * Enumerable#collect([iterator = Prototype.K[, context]]) -> Array * * Returns the results of applying the iterator to each element. @@ -89,7 +168,7 @@ var Enumerable = (function() { return results; } - /** alias of: Enumerable#find + /** * Enumerable#detect(iterator[, context]) -> firstElement | undefined * * Finds the first element for which the iterator returns a “truthy” value. @@ -106,7 +185,7 @@ var Enumerable = (function() { return result; } - /** alias of: select + /** * Enumerable#findAll(iterator[, context]) -> Array * * Returns all the elements for which the iterator returned “truthy” value. @@ -141,7 +220,7 @@ var Enumerable = (function() { return results; } - /** alias of: Enumerable#member + /** * Enumerable#include(object) -> Boolean * * Determines whether a given object is in the Enumerable or not, @@ -304,11 +383,10 @@ var Enumerable = (function() { }).pluck('value'); } - /** alias of: Enumerable#entries + /** * Enumerable#toArray() -> Array * * Returns an Array representation of the enumeration. - * Aliased as [[Enumerable#entries]]. **/ function toArray() { return this.map(); @@ -342,7 +420,7 @@ var Enumerable = (function() { return this.toArray().length; } - /** related to: Object.inspect + /** * Enumerable#inspect() -> String * * Returns the debug-oriented string representation of the object. @@ -351,6 +429,38 @@ var Enumerable = (function() { return '#'; } + /** alias of: Enumerable#collect + * Enumerable#map([iterator = Prototype.K[, context]]) -> Array + **/ + + /** alias of: Enumerable#any + * Enumerable#some([iterator = Prototype.K[, context]]) -> Boolean + **/ + + /** alias of: Enumerable#all + * Enumerable#every([iterator = Prototype.K[, context]]) -> Boolean + **/ + + /** alias of: Enumerable#findAll + * Enumerable#select(iterator[, context]) -> Array + **/ + + /** alias of: Enumerable#findAll + * Enumerable#filter(iterator[, context]) -> Array + **/ + + /** alias of: Enumerable#include + * Enumerable#member(object) -> Boolean + **/ + + /** alias of: Enumerable#toArray + * Enumerable#entries() -> Array + **/ + + /** alias of: Enumerable#detect + * Enumerable#find(iterator[, context]) -> firstElement | undefined + **/ + return { each: each, eachSlice: eachSlice,