jsduck 3.0.pre → 3.0.pre2

data/js-classes/Function.js

@@ -0,0 +1,256 @@
+/**
+ * @class Function
+ *
+ * Every function in JavaScript is actually a `Function` object.
+ *
+ * `Function` objects created with the `Function` constructor are parsed when the
+ * function is created. This is less efficient than declaring a function and
+ * calling it within your code, because functions declared with the function
+ * statement are parsed with the rest of the code.
+ *
+ * All arguments passed to the function are treated as the names of the
+ * identifiers of the parameters in the function to be created, in the order in
+ * which they are passed.
+ *
+ * Invoking the `Function` constructor as a function (without using the `new`
+ * operator) has the same effect as invoking it as a constructor.
+ *
+ * # Specifying arguments with the `Function` constructor
+ *
+ * The following code creates a `Function` object that takes two arguments.
+ *
+ *     // Example can be run directly in your JavaScript console
+ *
+ *     // Create a function that takes two arguments and returns the sum of those
+ *     arguments
+ *     var adder = new Function("a", "b", "return a + b");
+ *
+ *     // Call the function
+ *     adder(2, 6);
+ *     // > 8
+ *
+ * The arguments "a" and "b" are formal argument names that are used in the
+ * function body, "return a + b".
+ *
+ * <div class="notice">
+ * Documentation for this class comes from <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Function">MDN</a>
+ * and is available under <a href="http://creativecommons.org/licenses/by-sa/2.0/">Creative Commons: Attribution-Sharealike license</a>.
+ * </div>
+ */
+
+/**
+ * @method constructor
+ * Creates new Function object.
+ *
+ * @param {String...} args
+ * Names to be used by the function as formal argument names. Each must be a
+ * string that corresponds to a valid JavaScript identifier or a list of such
+ * strings separated with a comma; for example "`x`", "`theValue`", or "`a,b`".
+ * @param {String} functionBody
+ * A string containing the JavaScript statements comprising the function
+ * definition.
+ */
+
+// Properties
+
+/**
+ * @property {Number} length
+ * Specifies the number of arguments expected by the function.
+ */
+
+//Methods
+
+/**
+ * @method apply
+ * Applies the method of another object in the context of a different object (the
+ * calling object); arguments can be passed as an Array object.
+ *
+ * You can assign a different this object when calling an existing function. `this` refers to the
+ * current object, the calling object. With `apply`, you can write a method once and then inherit it
+ * in another object, without having to rewrite the method for the new object.
+ *
+ * `apply` is very similar to call, except for the type of arguments it supports. You can use an
+ * arguments array instead of a named set of parameters. With apply, you can use an array literal, for
+ * example, `fun.apply(this, ['eat', 'bananas'])`, or an Array object, for example, `fun.apply(this,
+ * new Array('eat', 'bananas'))`.
+ *
+ * You can also use arguments for the `argsArray` parameter. `arguments` is a local variable of a
+ * function. It can be used for all unspecified arguments of the called object. Thus, you do not have
+ * to know the arguments of the called object when you use the `apply` method. You can use arguments
+ * to pass all the arguments to the called object. The called object is then responsible for handling
+ * the arguments.
+ *
+ * Since ECMAScript 5th Edition you can also use any kind of object which is array like, so in
+ * practice this means it's going to have a property length and integer properties in the range
+ * `[0...length)`. As an example you can now use a NodeList or a own custom object like `{'length': 2,
+ * '0': 'eat', '1': 'bananas'}`.
+ *
+ * You can use `apply` to chain constructors for an object, similar to Java. In the following example,
+ * the constructor for the `Product` object is defined with two parameters, `name` and `value`. Two
+ * other functions `Food` and `Toy` invoke `Product` passing `this` and `arguments`. `Product`
+ * initializes the properties `name` and `price`, both specialized functions define the category. In
+ * this example, the `arguments` object is fully passed to the product constructor and corresponds to
+ * the two defined parameters.
+ *
+ *     function Product(name, price) {
+ *         this.name = name;
+ *         this.price = price;
+ *
+ *         if (price < 0)
+ *             throw RangeError('Cannot create product "' + name + '" with a negative price');
+ *         return this;
+ *     }
+ *
+ *     function Food(name, price) {
+ *         Product.apply(this, arguments);
+ *         this.category = 'food';
+ *     }
+ *     Food.prototype = new Product();
+ *
+ *     function Toy(name, price) {
+ *         Product.apply(this, arguments);
+ *         this.category = 'toy';
+ *     }
+ *     Toy.prototype = new Product();
+ *
+ *     var cheese = new Food('feta', 5);
+ *     var fun = new Toy('robot', 40);
+ *
+ * Clever usage of `apply` allows you to use built-ins functions for some tasks that otherwise
+ * probably would have been written by looping over the array values. As an example here we are going
+ * to use Math.max/Math.min to find out the maximum/minimum value in an array.
+ *
+ *     //min/max number in an array
+ *     var numbers = [5, 6, 2, 3, 7];
+ *
+ *     //using Math.min/Math.max apply
+ *     var max = Math.max.apply(null, numbers); // This about equal to Math.max(numbers[0], ...) or
+ *     // Math.max(5, 6, ..)
+ *     var min = Math.min.apply(null, numbers);
+ *
+ *     //vs. simple loop based algorithm
+ *     max = -Infinity, min = +Infinity;
+ *
+ *     for (var i = 0; i < numbers.length; i++) {
+ *     if (numbers[i] > max)
+ *         max = numbers[i];
+ *     if (numbers[i] < min)
+ *         min = numbers[i];
+ *     }
+ *
+ * But beware: in using `apply` this way, you run the risk of exceeding the JavaScript engine's
+ * argument length limit. The consequences of applying a function with too many arguments (think more
+ * than tens of thousands of arguments) vary across engines, because the limit (indeed even the nature
+ * of any excessively-large-stack behavior) is unspecified. Some engines will throw an exception. More
+ * perniciously, others will arbitrarily limit the number of arguments actually passed to the applied
+ * function. (To illustrate this latter case: if such an engine had a limit of four arguments [actual
+ * limits are of course significantly higher], it would be as if the arguments 5, 6, 2, 3 had been
+ * passed to apply in the examples above, rather than the full array.)  If your value array might grow
+ * into the tens of thousands, use a hybrid strategy: apply your function to chunks of the array at a
+ * time:
+ *
+ *     function minOfArray(arr)
+ *     {
+ *         var min = Infinity;
+ *         var QUANTUM = 32768;
+ *         for (var i = 0, len = arr.length; i < len; i += QUANTUM)
+ *         {
+ *             var submin = Math.min.apply(null, numbers.slice(i, Math.min(i + QUANTUM, len)));
+ *             min = Math.min(submin, min);
+ *         }
+ *     return min;
+ *     }
+ *
+ *     var min = minOfArray([5, 6, 2, 3, 7]);
+ *
+ * @param {Object} thisArg The value of this provided for the call to fun. Note that this may not be
+ * the actual value seen by the method: if the method is a function in non-strict mode code, null and
+ * undefined will be replaced with the global object, and primitive values will be boxed.
+ * @param {Array} argsArray An array like object, specifying the arguments with which fun should be
+ * called, or null or undefined if no arguments should be provided to the function.
+ * @return {Object} Returns what the function returns.
+ */
+
+/**
+ * @method call
+ * Calls (executes) a method of another object in the context of a different
+ * object (the calling object); arguments can be passed as they are.
+ *
+ * You can assign a different this object when calling an existing function. `this` refers to the
+ * current object, the calling object.
+ *
+ * With `call`, you can write a method once and then inherit it in another object, without having to
+ * rewrite the method for the new object.
+ *
+ * You can use call to chain constructors for an object, similar to Java. In the following example,
+ * the constructor for the product object is defined with two parameters, name and value. Another
+ * object, `prod_dept`, initializes its unique variable (`dept`) and calls the constructor for
+ * `product` in its constructor to initialize the other variables.
+ *
+ *     function Product(name, price) {
+ *         this.name = name;
+ *         this.price = price;
+ *
+ *         if (price < 0)
+ *             throw RangeError('Cannot create product "' + name + '" with a negative price');
+ *         return this;
+ *     }
+ *
+ *     function Food(name, price) {
+ *         Product.call(this, name, price);
+ *         this.category = 'food';
+ *     }
+ *     Food.prototype = new Product();
+ *
+ *     function Toy(name, price) {
+ *         Product.call(this, name, price);
+ *         this.category = 'toy';
+ *     }
+ *     Toy.prototype = new Product();
+ *
+ *     var cheese = new Food('feta', 5);
+ *     var fun = new Toy('robot', 40);
+ *
+ * In this purely constructed example, we create anonymous function and use `call` to invoke it on
+ * every object in an array. The main purpose of the anonymous function here is to add a print
+ * function to every object, which is able to print the right index of the object in the array.
+ * Passing the object as `this` value was not strictly necessary, but is done for explanatory purpose.
+ *
+ *     var animals = [
+ *     {species: 'Lion', name: 'King'},
+ *     {species: 'Whale', name: 'Fail'}
+ *     ];
+ *
+ *     for (var i = 0; i < animals.length; i++) {
+ *         (function (i) {
+ *         this.print = function () {
+ *             console.log('#' + i  + ' ' + this.species + ': ' + this.name);
+ *         }
+ *     }).call(animals[i], i);
+ *     }
+ *
+ * @param {Object} thisArg The value of this provided for the call to `fun`.Note that this may not be
+ * the actual value seen by the method: if the method is a function in non-strict mode code, `null`
+ * and `undefined` will be replaced with the global object, and primitive values will be boxed.
+ * @param {Object...} args Arguments for the object.
+ * @return {Object} Returns what the function returns.
+ */
+
+/**
+ * @method toString
+ * Returns a string representing the source code of the function. Overrides the
+ * `Object.toString` method.
+ *
+ * The {@link Function} object overrides the `toString` method of the Object object; it does
+ * not inherit Object.toString. For `Function` objects, the `toString` method returns a string
+ * representation of the object.
+ *
+ * JavaScript calls the `toString` method automatically when a `Function` is to be represented as a
+ * text value or when a Function is referred to in a string concatenation.
+ *
+ * For `Function` objects, the built-in `toString` method decompiles the function back into the
+ * JavaScript source that defines the function. This string includes the `function` keyword, the
+ * argument list, curly braces, and function body.
+ *
+ * @return {String} The function as a string.
+ */

data/js-classes/Number.js

@@ -0,0 +1,308 @@
+/**
+ * @class Number
+ *
+ * Creates a wrapper object to allow you to work with numerical values.
+ *
+ * The primary uses for the `Number` object are:
+ *
+ * If the argument cannot be converted into a number, it returns `NaN`.
+ *
+ * In a non-constructor context (i.e., without the `new` operator), `Number` can
+ * be used to perform a type conversion.
+ *
+ * # Using the `Number` object to assign values to numeric variables
+ *
+ * The following example uses the `Number` object's properties to assign values to
+ * several numeric variables:
+ *
+ *     biggestNum = Number.MAX_VALUE;
+ *     smallestNum = Number.MIN_VALUE;
+ *     infiniteNum = Number.POSITIVE_INFINITY;
+ *     negInfiniteNum = Number.NEGATIVE_INFINITY;
+ *     notANum = Number.NaN;
+ *
+ * # Using `Number` to convert a `Date` object
+ *
+ * The following example converts the `Date` object to a numerical value using
+ * `Number` as a function:
+ *
+ *     var d = new Date("December 17, 1995 03:24:00");
+ *     print(Number(d));
+ *
+ * This displays "819199440000".
+ *
+ * The following example converts the Date object to a numerical value using
+ * `Number` as a function:
+ *
+ * <div class="notice">
+ * Documentation for this class comes from <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Number">MDN</a>
+ * and is available under <a href="http://creativecommons.org/licenses/by-sa/2.0/">Creative Commons: Attribution-Sharealike license</a>.
+ * </div>
+ */
+
+/**
+ * @method constructor
+ * Creates new Number object.
+ * @param value
+ * The numeric value of the object being created.
+ */
+
+//Properties
+
+/**
+ * @property {Number} MAX_VALUE
+ * @static
+ * The largest positive representable number. The largest negative representable
+ * number is `-MAX_VALUE`.
+ *
+ * The `MAX_VALUE` property has a value of approximately 1.79E+308. Values larger than `MAX_VALUE` are
+ * represented as `"Infinity"`.
+ *
+ * Because `MAX_VALUE` is a static property of `Number`, you always use it as `Number.MAX_VALUE`,
+ * rather than as a property of a `Number` object you created.
+ *
+ * The following code multiplies two numeric values. If the result is less than or equal to
+ * `MAX_VALUE`, the `func1` function is called; otherwise, the `func2` function is called.
+ *
+ *     if (num1 * num2 <= Number.MAX_VALUE)
+ *         func1();
+ *     else
+ *         func2();
+ */
+
+/**
+ * @property {Number} MIN_VALUE
+ * @static
+ * The smallest positive representable number -- that is, the positive number
+ * closest to zero (without actually being zero). The smallest negative
+ * representable number is `-MIN_VALUE`.
+ *
+ * The `MIN_VALUE` property is the number closest to 0, not the most negative number, that JavaScript
+ * can represent.
+ *
+ * `MIN_VALUE` has a value of approximately 5e-324. Values smaller than `MIN_VALUE` ("underflow
+ * values") are converted to 0.
+ *
+ * Because `MIN_VALUE` is a static property of `Number`, you always use it as `Number.MIN_VALUE`,
+ * rather than as a property of a `Number` object you created.
+ *
+ * The following code divides two numeric values. If the result is greater than or equal to
+ * `MIN_VALUE`, the `func1` function is called; otherwise, the `func2` function is called.
+ *
+ *     if (num1 / num2 >= Number.MIN_VALUE)
+ *         func1()
+ *     else
+ *         func2()
+ */
+
+/**
+ * @property {Number} NaN
+ * @static
+ * Special "not a number" value.
+ */
+
+/**
+ * @property {Number} NEGATIVE_INFINITY
+ * Special value representing negative infinity; returned on overflow.
+ *
+ * The value of `Number.NEGATIVE_INFINITY` is the same as the negative value of the global object's
+ * Infinity property.
+ *
+ * This value behaves slightly differently than mathematical infinity:
+ *
+ * *   Any positive value, including POSITIVE_INFINITY, multiplied by NEGATIVE_INFINITY is NEGATIVE_INFINITY.
+ * *   Any negative value, including NEGATIVE_INFINITY, multiplied by NEGATIVE_INFINITY is
+ * POSITIVE_INFINITY.
+ * *   Zero multiplied by NEGATIVE_INFINITY is NaN.
+ * *   NaN multiplied by NEGATIVE_INFINITY is NaN.
+ * *   NEGATIVE_INFINITY, divided by any negative value except NEGATIVE_INFINITY, is
+ * POSITIVE_INFINITY.
+ * *   NEGATIVE_INFINITY, divided by any positive value except POSITIVE_INFINITY, is
+ * NEGATIVE_INFINITY.
+ * *   NEGATIVE_INFINITY, divided by either NEGATIVE_INFINITY or POSITIVE_INFINITY, is NaN.
+ * *   Any number divided by NEGATIVE_INFINITY is Zero.
+ *
+ * Several JavaScript methods (such as the `Number` constructor, `parseFloat`, and `parseInt`) return
+ * `NaN` if the value specified in the parameter is significantly lower than `Number.MIN_VALUE`.
+ *
+ * You might use the `Number.NEGATIVE_INFINITY` property to indicate an error condition that returns a
+ * finite number in case of success. Note, however, that `isFinite` would be more appropriate in such
+ * a case.
+ *
+ * In the following example, the variable smallNumber is assigned a value that is smaller than the
+ * minimum value. When the `if` statement executes, `smallNumber` has the value `"-Infinity"`, so
+ * `smallNumber` is set to a more manageable value before continuing.
+ *
+ *     var smallNumber = (-Number.MAX_VALUE) * 2
+ *     if (smallNumber == Number.NEGATIVE_INFINITY) {
+ *         smallNumber = returnFinite();
+ *     }
+ */
+
+/**
+ * @property {Number} POSITIVE_INFINITY
+ * Special value representing infinity; returned on overflow.
+ *
+ * The value of `Number.POSITIVE_INFINITY` is the same as the value of the global object's Infinity
+ * property.
+ *
+ * This value behaves slightly differently than mathematical infinity:
+ *
+ * *   Any positive value, including POSITIVE_INFINITY, multiplied by POSITIVE_INFINITY is
+ * POSITIVE_INFINITY.
+ * *   Any negative value, including NEGATIVE_INFINITY, multiplied by POSITIVE_INFINITY is
+ * NEGATIVE_INFINITY.
+ * *   Zero multiplied by POSITIVE_INFINITY is NaN.
+ * *   NaN multiplied by POSITIVE_INFINITY is NaN.
+ * *   POSITIVE_INFINITY, divided by any negative value except NEGATIVE_INFINITY, is
+ * NEGATIVE_INFINITY.
+ * *   POSITIVE_INFINITY, divided by any positive value except POSITIVE_INFINITY, is
+ * POSITIVE_INFINITY.
+ * *   POSITIVE_INFINITY, divided by either NEGATIVE_INFINITY or POSITIVE_INFINITY, is NaN.
+ * *   Any number divided by POSITIVE_INFINITY is Zero.
+ *
+ * Several JavaScript methods (such as the `Number` constructor, `parseFloat`, and `parseInt`) return
+ * `NaN` if the value specified in the parameter is significantly higher than `Number.MAX_VALUE`.
+ *
+ * You might use the `Number.POSITIVE_INFINITY` property to indicate an error condition that returns a
+ * finite number in case of success. Note, however, that `isFinite` would be more appropriate in such
+ * a case.
+ *
+ * In the following example, the variable `bigNumber` is assigned a value that is larger than the
+ * maximum value. When the if statement executes, `bigNumber` has the value "Infinity", so `bigNumber`
+ * is set to a more manageable value before continuing.
+ *
+ *     var bigNumber = Number.MAX_VALUE * 2
+ *     if (bigNumber == Number.POSITIVE_INFINITY) {
+ *         bigNumber = returnFinite();
+ *     }
+ */
+
+//Methods
+
+/**
+ * @method toExponential
+ * Returns a string representing the number in exponential notation.
+ *
+ * A string representing a `Number` object in exponential notation with one digit before the decimal
+ * point, rounded to `fractionDigits` digits after the decimal point. If the `fractionDigits` argument
+ * is omitted, the number of digits after the decimal point defaults to the number of digits necessary
+ * to represent the value uniquely.
+ *
+ * If you use the `toExponential` method for a numeric literal and the numeric literal has no exponent
+ * and no decimal point, leave a space before the dot that precedes the method call to prevent the dot
+ * from being interpreted as a decimal point.
+ *
+ * If a number has more digits that requested by the `fractionDigits` parameter, the number is rounded
+ * to the nearest number represented by `fractionDigits` digits. See the discussion of rounding in the
+ * description of the `toFixed` method, which also applies to `toExponential`.
+ *
+ *     var num=77.1234;
+ *
+ *     alert("num.toExponential() is " + num.toExponential()); //displays 7.71234e+1
+ *
+ *     alert("num.toExponential(4) is " + num.toExponential(4)); //displays 7.7123e+1
+ *
+ *     alert("num.toExponential(2) is " + num.toExponential(2)); //displays 7.71e+1
+ *
+ *     alert("77.1234.toExponential() is " + 77.1234.toExponential()); //displays 7.71234e+1
+ *
+ *     alert("77 .toExponential() is " + 77 .toExponential()); //displays 7.7e+1
+ *
+ * @param {Number} fractionDigits An integer specifying the number of digits after the decimal
+ * point. Defaults to as many digits as necessary to specify the number.
+ * @return {String} Exponential notation of number.
+ */
+
+/**
+ * @method toFixed
+ * Returns a string representing the number in fixed-point notation.
+ *
+ * @return {String} A string representation of `number` that does not use
+ * exponential notation and has exactly `digits` digits after the decimal place.
+ * The number is rounded if necessary, and the fractional part is padded with
+ * zeros if necessary so that it has the specified length. If `number` is greater
+ * than 1e+21, this method simply calls `Number.toString()` and returns a string
+ * in exponential notation.
+ *
+ * @param {Number} digits The number of digits to appear after the decimal point; this may be a
+ * value between 0 and 20, inclusive, and implementations may optionally support a larger range of
+ * values. If this argument is omitted, it is treated as 0.
+ */
+
+/**
+ * @method toLocaleString
+ * Returns a human readable string representing the number using the locale of the
+ * environment. Overrides the `Object.prototype.toLocaleString` method.
+ *
+ * This method available to numbers will convert the number into a string which is suitable for
+ * presentation in the given locale.
+ *
+ *     var number = 3500
+ *     console.log(number.toLocaleString()); // Displays "3,500" in English locale
+ *
+ * @return {String} String representing the number.
+ */
+
+/**
+ * @method toPrecision
+ * Returns a string representing the number to a specified precision in fixed-
+ * point or exponential notation.
+ *
+ * A string representing a `Number` object in fixed-point or
+ * exponential notation rounded to precision significant digits. See the
+ * discussion of rounding in the description of the `toFixed` method, which also
+ * applies to `toPrecision`.
+ *
+ * If the precision argument is omitted, behaves as Number.toString. If it is a
+ * non-integer value, it is rounded to the nearest integer. After rounding, if
+ * that value is not between 1 and 100 (inclusive), a RangeError is thrown.
+ *
+ * @param {Number} precision An integer specifying the number of significant digits.
+ * @return {String} String that represents `Number` object.
+ */
+
+/**
+ * @method toString
+ * Returns a string representing the specified object. Overrides the
+ * `Object.prototype.toString` method.
+ *
+ * The `Number` object overrides the `toString` method of the `Object` object; it does not inherit
+ * `Object.toString`. For `Number` objects, the toString method returns a string representation of the
+ * object in the specified radix.
+ *
+ * The `toString` method parses its first argument, and attempts to return a string representation in
+ * the specified radix (base). For radixes above 10, the letters of the alphabet indicate numerals
+ * greater than 9. For example, for hexadecimal numbers (base 16), A through F are used.
+ *
+ * If `toString` is given a radix not between 2 and 36, an exception is thrown.
+ *
+ * If the radix is not specified, JavaScript assumes the preferred radix is 10.
+ *
+ *     var count = 10;
+ *     print(count.toString());   // displays "10"
+ *     print((17).toString());    // displays "17"
+ *
+ *     var x = 7;
+ *     print(x.toString(2));      // displays "111"
+ *
+ * @param {Number} radix An integer between 2 and 36 specifying the base to use for representing
+ * numeric values.
+ * @return {String} The number represented as a string.
+ */
+
+/**
+ * @method valueOf
+ * Returns the primitive value of the specified object. Overrides the
+ * `Object.prototype.valueOf` method.
+ *
+ * The `valueOf` method of `Number` returns the primitive value of a `Number` object as a number data
+ * type.
+ *
+ * This method is usually called internally by JavaScript and not explicitly in code.
+ *
+ *     var x = new Number();
+ *     print(x.valueOf());     // prints "0"
+ *
+ * @return {Number} The primitive value of the number.
+ */