@@ -1 +1,2 @@ build +pdoc .gitignore @@ -1,24 +1,22 @@ <%= license %> /** - * @overview - * This file contains a set of 'global' functions used throughout JS.Class. All functions are - * members of the JS object. All general utility functions (i.e. those not attached to a - * particular class or module) should be placed here. - * - * Do not assume any of these functions are part of the public API. They are essentially - * plumbing for JS.Class's internals and may change or disappear in future releases. - */ + * == utils == + **/ +/** section: utils + * JS + **/ JS = { - /** + /** section: utils + * JS.extend(target, extensions) -> Object + * - target (Object): object to be extended + * - extensions (Object): object containing key/value pairs to add to target + * * Adds the properties of the second argument to the first, and returns the first. Will not * needlessly overwrite fields with identical values; if an object has inherited a property * we should not add the property to the object itself. - * @param {Object} target - * @param {Object} extensions - * @returns {Object} - */ + **/ extend: function(target, extensions) { extensions = extensions || {}; for (var prop in extensions) { @@ -28,11 +26,12 @@ JS = { return target; }, - /** + /** section: utils + * JS.makeFunction() -> Function + * * Returns a function for use as a constructor. These functions are used as the basis for * classes. The constructor calls the object's initialize() method if it exists. - * @returns {Function} - */ + **/ makeFunction: function() { return function() { return this.initialize @@ -41,44 +40,46 @@ JS = { }; }, - /** + /** section: utils + * JS.makeBridge(klass) -> Object + * - klass (JS.Class): class from which you want to inherit + * * Takes a class and returns an instance of it, without calling the class's constructor. * Used for forging links between objects using JavaScript's inheritance model. - * @param {Class} klass - * @returns {Object} - */ + **/ makeBridge: function(klass) { var bridge = function() {}; bridge.prototype = klass.prototype; return new bridge; }, - /** + /** section: utils + * JS.delegate(property, method) -> Function + * - property (String): name of instance variable to delegate to + * - method (String): name of method to call on delegate object + * * Returns a function used to delegate a method call to a property of an object. Used for * faking a subclass with manual delegation to the parent class. For example: * * JS.delegate('mod', 'lookup') * * // -> function() { return this.mod.lookup.apply(this.mod, arguments); } - * - * @param {String} property - * @param {String} method - * @returns {Function} - */ + **/ delegate: function(property, method) { return function() { return this[property][method].apply(this[property], arguments); }; }, - /** + /** section: utils + * JS.bind(object, func) -> Function + * - object (Object): object to bind the function to + * - func (Function): function that the bound function should call + * * Takes a function and an object, and returns a new function that calls the original * function with 'this' set to refer to the object. Used to implement Object#method, * amongst other things. - * @param {Function} - * @param {Object} - * @returns {Function} - */ + **/ bind: function() { var args = JS.array(arguments), method = args.shift(), object = args.shift() || null; return function() { @@ -86,39 +87,42 @@ JS = { }; }, - /** + /** section: utils + * JS.callsSuper(func) -> Boolean + * - func (Function): function to test for super() calls + * * Takes a function and returns true iff the function makes a call to callSuper(). Result * is cached on the function itself since functions are immutable and decompiling them * is expensive. We use this to determine whether to wrap the function when it's added * to a class; wrapping impedes performance and should be avoided where possible. - * @param {Function} func - * @returns {Boolean} - */ + **/ callsSuper: function(func) { return func.SUPER === undefined ? func.SUPER = /\bcallSuper\b/.test(func.toString()) : func.SUPER; }, - /** + /** section: utils + * JS.mask(func) -> Function + * - func (Function): function to obfuscate + * * Disguises a function so that we cannot tell if it uses callSuper(). Sometimes we don't * want such functions to be wrapped by the inheritance system. Modifies the function's * toString() method and returns the function. - * @param {Function} func - * @returns {Function} - */ + **/ mask: function(func) { var string = func.toString().replace(/callSuper/g, 'super'); func.toString = function() { return string }; return func; }, - /** + /** section: utils + * JS.array(iterable) -> Array + * - iterable (Object): object you want to cast to an Array + * * Takes any iterable object (something with a 'length' property) and returns a native * JavaScript Array containing the same elements. - * @param {Object} iterable - * @returns {Array} - */ + **/ array: function(iterable) { if (!iterable) return []; if (iterable.toArray) return iterable.toArray(); @@ -127,14 +131,15 @@ JS = { return results; }, - /** + /** section: utils + * JS.indexOf(haystack, needle) -> Number + * - haystack (Array): array to search + * - needle (Object): object to search for + * * Returns the index of the needle in the haystack, which is typically an Array or an * array-like object. Returns -1 if no matching element is found. We need this as older * IE versions don't implement Array#indexOf(). - * @param {Array} haystack - * @param {Object} needle - * @returns {Number} - */ + **/ indexOf: function(haystack, needle) { for (var i = 0, n = haystack.length; i < n; i++) { if (haystack[i] === needle) return i; @@ -142,22 +147,24 @@ JS = { return -1; }, - /** + /** section: utils + * JS.isFn(object) -> Boolean + * - object (Object): object to test + * * Returns true iff the argument is a function. - * @param {Object} object - * @returns {Boolean} - */ + **/ isFn: function(object) { return object instanceof Function; }, - /** + /** section: utils + * JS.ignore(key, object) -> Boolean + * - key (String): name of field being added to an object + * - object (Object): value of the given field + * * Used to determine whether a key-value pair should be added to a class or module. Pairs * may be ignored if they have some special function, like 'include' or 'extend'. - * @param {String} key - * @param {Object} object - * @returns {Boolean} - */ + **/ ignore: function(key, object) { return /^(include|extend)$/.test(key) && typeof object === 'object'; } source/core/utils.js 47eb56d0e6b24cb667c526dc45c8f7c7e7d3d736 James Coglan jcoglan@googlemail.com http://github.com/jcoglan/js.class/commit/6c1cb11ad916505e24e82fd40150205e73feeba0 6c1cb11ad916505e24e82fd40150205e73feeba0 2008-12-01T10:21:57-08:00 2008-12-01T10:21:57-08:00 Converting utils.js to PDoc format documentation. 7005406c577ae325bef1a00bbd6cce5e6ebf7ab3 James Coglan jcoglan@googlemail.com