diff options
| -rw-r--r-- | src/Angular.js | 92 | ||||
| -rw-r--r-- | src/Injector.js | 25 | ||||
| -rw-r--r-- | src/JSON.js | 10 | ||||
| -rw-r--r-- | src/directives.js | 48 | ||||
| -rw-r--r-- | src/jqLite.js | 29 | ||||
| -rw-r--r-- | src/markups.js | 28 |
6 files changed, 106 insertions, 126 deletions
diff --git a/src/Angular.js b/src/Angular.js index 69d52a2a..d5d862e0 100644 --- a/src/Angular.js +++ b/src/Angular.js @@ -6,26 +6,24 @@ if (typeof document.getAttribute == $undefined) document.getAttribute = function() {}; /** - * @workInProgress * @ngdoc function * @name angular.lowercase * @function * - * @description Converts string to lowercase - * @param {string} string String to be lowercased. + * @description Converts the specified string to lowercase. + * @param {string} string String to be converted to lowercase. * @returns {string} Lowercased string. */ var lowercase = function (string){ return isString(string) ? string.toLowerCase() : string; }; /** - * @workInProgress * @ngdoc function * @name angular.uppercase * @function * - * @description Converts string to uppercase. - * @param {string} string String to be uppercased. + * @description Converts the specified string to uppercase. + * @param {string} string String to be converted to uppercase. * @returns {string} Uppercased string. */ var uppercase = function (string){ return isString(string) ? string.toUpperCase() : string; }; @@ -112,17 +110,15 @@ var _undefined = undefined, DATE_ISOSTRING_LN = 24; /** - * @workInProgress * @ngdoc function * @name angular.forEach * @function * * @description - * Invokes the `iterator` function once for each item in `obj` collection. The collection can - * either be an object or an array. The `iterator` function is invoked with `iterator(value, key)`, - * where `value` is the value of an object property or an array element and `key` is the object - * property key or array element index. Optionally, `context` can be specified for the iterator - * function. + * Invokes the `iterator` function once for each item in `obj` collection, which can be either an + * object or an array. The `iterator` function is invoked with `iterator(value, key)`, where `value` + * is the value of an object property or an array element and `key` is the object property key or + * array element index. Specifying a `context` for the function is optional. * * Note: this function was previously known as `angular.foreach`. * @@ -137,7 +133,7 @@ var _undefined = undefined, * * @param {Object|Array} obj Object to iterate over. * @param {function()} iterator Iterator function. - * @param {Object} context Object to become context (`this`) for the iterator function. + * @param {Object=} context Object to become context (`this`) for the iterator function. * @returns {Object|Array} Reference to `obj`. */ function forEach(obj, iterator, context) { @@ -217,7 +213,6 @@ function nextUid() { } /** - * @workInProgress * @ngdoc function * @name angular.extend * @function @@ -226,8 +221,8 @@ function nextUid() { * Extends the destination object `dst` by copying all of the properties from the `src` object(s) * to `dst`. You can specify multiple `src` objects. * - * @param {Object} dst The destination object. - * @param {...Object} src The source object(s). + * @param {Object} dst Destination object. + * @param {...Object} src Source object(s). */ function extend(dst) { forEach(arguments, function(obj){ @@ -247,14 +242,13 @@ function inherit(parent, extra) { /** - * @workInProgress * @ngdoc function * @name angular.noop * @function * * @description - * Empty function that performs no operation whatsoever. This function is useful when writing code - * in the functional style. + * A function that performs no operations. This function can be useful when writing code in the + * functional style. <pre> function foo(callback) { var result = calculateResult(); @@ -266,14 +260,13 @@ function noop() {} /** - * @workInProgress * @ngdoc function * @name angular.identity * @function * * @description - * A function that does nothing except for returning its first argument. This function is useful - * when writing code in the functional style. + * A function that returns its first argument. This function is useful when writing code in the + * functional style. * <pre> function transformer(transformationFn, value) { @@ -298,13 +291,12 @@ function extensionMap(angular, name, transform) { } /** - * @workInProgress * @ngdoc function * @name angular.isUndefined * @function * * @description - * Checks if a reference is undefined. + * Determines if a reference is undefined. * * @param {*} value Reference to check. * @returns {boolean} True if `value` is undefined. @@ -313,13 +305,12 @@ function isUndefined(value){ return typeof value == $undefined; } /** - * @workInProgress * @ngdoc function * @name angular.isDefined * @function * * @description - * Checks if a reference is defined. + * Determines if a reference is defined. * * @param {*} value Reference to check. * @returns {boolean} True if `value` is defined. @@ -328,14 +319,13 @@ function isDefined(value){ return typeof value != $undefined; } /** - * @workInProgress * @ngdoc function * @name angular.isObject * @function * * @description - * Checks if a reference is an `Object`. Unlike in JavaScript `null`s are not considered to be - * objects. + * Determines if a reference is an `Object`. Unlike `typeof` in JavaScript, `null`s are not + * considered to be objects. * * @param {*} value Reference to check. * @returns {boolean} True if `value` is an `Object` but not `null`. @@ -344,13 +334,12 @@ function isObject(value){ return value!=null && typeof value == $object;} /** - * @workInProgress * @ngdoc function * @name angular.isString * @function * * @description - * Checks if a reference is a `String`. + * Determines if a reference is a `String`. * * @param {*} value Reference to check. * @returns {boolean} True if `value` is a `String`. @@ -359,13 +348,12 @@ function isString(value){ return typeof value == $string;} /** - * @workInProgress * @ngdoc function * @name angular.isNumber * @function * * @description - * Checks if a reference is a `Number`. + * Determines if a reference is a `Number`. * * @param {*} value Reference to check. * @returns {boolean} True if `value` is a `Number`. @@ -374,13 +362,12 @@ function isNumber(value){ return typeof value == $number;} /** - * @workInProgress * @ngdoc function * @name angular.isDate * @function * * @description - * Checks if value is a date. + * Determines if a value is a date. * * @param {*} value Reference to check. * @returns {boolean} True if `value` is a `Date`. @@ -389,13 +376,12 @@ function isDate(value){ return value instanceof Date; } /** - * @workInProgress * @ngdoc function * @name angular.isArray * @function * * @description - * Checks if a reference is an `Array`. + * Determines if a reference is an `Array`. * * @param {*} value Reference to check. * @returns {boolean} True if `value` is an `Array`. @@ -404,13 +390,12 @@ function isArray(value) { return value instanceof Array; } /** - * @workInProgress * @ngdoc function * @name angular.isFunction * @function * * @description - * Checks if a reference is a `Function`. + * Determines if a reference is a `Function`. * * @param {*} value Reference to check. * @returns {boolean} True if `value` is a `Function`. @@ -516,7 +501,7 @@ function map(obj, iterator, context) { * * @param {Object|Array|string} obj Object, array, or string to inspect. * @param {boolean} [ownPropsOnly=false] Count only "own" properties in an object - * @returns {number} The size of `obj` or `0` if `obj` is neither an object or an array. + * @returns {number} The size of `obj` or `0` if `obj` is neither an object nor an array. * * @example * <doc:example> @@ -583,7 +568,6 @@ function isLeafNode (node) { } /** - * @workInProgress * @ngdoc function * @name angular.copy * @function @@ -814,17 +798,14 @@ function sliceArgs(args, startIndex) { /** - * @workInProgress * @ngdoc function * @name angular.bind * @function * * @description - * Returns a function which calls function `fn` bound to `self` - * (`self` becomes the `this` for `fn`). - * - * Optional `args` can be supplied which are prebound to the function, also known as - * [function currying](http://en.wikipedia.org/wiki/Currying). + * Returns a function which calls function `fn` bound to `self` (`self` becomes the `this` for + * `fn`). You can supply optional `args` that are are prebound to the function. This feature is also + * known as [function currying](http://en.wikipedia.org/wiki/Currying). * * @param {Object} self Context which `fn` should be evaluated in. * @param {function()} fn Function to be bound. @@ -846,8 +827,7 @@ function bind(self, fn) { : fn.call(self); }; } else { - // in IE, native methods are not functions and so they can not be bound - // (but they don't need to be) + // in IE, native methods are not functions so they cannot be bound (note: they don't need to be) return fn; } } @@ -1034,14 +1014,14 @@ function assertArgFn(arg, name) { * @ngdoc property * @name angular.version * @description - * Object which contains information about the current AngularJS version. The object has following - * properties: + * An object that contains information about the current AngularJS version. This object has the + * following properties: * - * - `full` – `{string}` – full version string, e.g. "0.9.18" - * - `major` – `{number}` – major version number, e.g. 0 - * - `minor` – `{number}` – minor version number, e.g. 9 - * - `dot` – `{number}` – dot version number, e.g. 18 - * - `codeName` – `{string}` – code name of the release, e.g. "jiggling-armfat" + * - `full` – `{string}` – Full version string, such as "0.9.18". + * - `major` – `{number}` – Major version number, such as "0". + * - `minor` – `{number}` – Minor version number, such as "9". + * - `dot` – `{number}` – Dot version number, such as "18". + * - `codeName` – `{string}` – Code name of the release, such as "jiggling-armfat". */ var version = { full: '"NG_VERSION_FULL"', // all of these placeholder strings will be replaced by rake's diff --git a/src/Injector.js b/src/Injector.js index d2bafcf5..912e911c 100644 --- a/src/Injector.js +++ b/src/Injector.js @@ -10,11 +10,12 @@ * dependency injection (see {@link guide/dev_guide.di dependency injection}). * * Angular creates an injector automatically for the root scope and it is available as the - * {@link angular.scope.$service $service} property. Creation of the injector automatically creates - * all of the `$eager` {@link angular.service services}. + * {@link angular.scope.$service $service} property. Creating an injector doesn't automatically + * create all of the `$eager` {@link angular.service services}. You have to call `injector.eager()` + * to initialize them. * - * @param {Object=} [factoryScope={}] `this` for the service factory function. - * @param {Object.<string, function()>=} [factories=angular.service] Map of service factory + * @param {Object=} [factoryScope={}] The `this` for the service factory function. + * @param {Object.<string, function()>=} [factories=angular.service] Map of the service factory * functions. * @param {Object.<string, function()>=} [instanceCache={}] Place where instances of services are * saved for reuse. Can also be used to override services specified by `serviceFactory` @@ -22,19 +23,19 @@ * @returns {function()} Injector function: * * * `injector(serviceName)`: - * * `serviceName` - `{string=}` - name of the service to retrieve. + * * `serviceName` - `{string=}` - Name of the service to retrieve. * * The injector function also has these properties: * - * * an `invoke` property which can be used to invoke methods with dependency-injected arguments. + * * An `invoke` property which can be used to invoke methods with dependency-injected arguments. * `injector.invoke(self, fn, curryArgs)` - * * `self` - "`this`" to be used when invoking the function. - * * `fn` - the function to be invoked. The function may have the `$inject` property which - * lists the set of arguments which should be auto injected + * * `self` - The "`this`" to be used when invoking the function. + * * `fn` - The function to be invoked. The function may have the `$inject` property that + * lists the set of arguments which should be auto-injected. * (see {@link guide/dev_guide.di dependency injection}). - * * `curryArgs(array)` - optional array of arguments to pass to function invocation after the - * injection arguments (also known as curry arguments or currying). - * * an `eager` property which is used to initialize the eager services. + * * `curryArgs(array)` - Optional array of arguments to pass to the function + * invocation after the injection arguments (also known as curry arguments or currying). + * * An `eager` property which is used to initialize the eager services. * `injector.eager()` */ function createInjector(factoryScope, factories, instanceCache) { diff --git a/src/JSON.js b/src/JSON.js index 34bcfd51..1dc5cc03 100644 --- a/src/JSON.js +++ b/src/JSON.js @@ -3,15 +3,14 @@ var array = [].constructor; /** - * @workInProgress * @ngdoc function * @name angular.toJson * @function * * @description - * Serializes the input into a JSON formated string. + * Serializes input into a JSON-formatted string. * - * @param {Object|Array|Date|string|number} obj Input to jsonify. + * @param {Object|Array|Date|string|number} obj Input to be serialized into JSON. * @param {boolean=} pretty If set to true, the JSON output will contain newlines and whitespace. * @returns {string} Jsonified string representing `obj`. */ @@ -22,16 +21,15 @@ function toJson(obj, pretty) { } /** - * @workInProgress * @ngdoc function * @name angular.fromJson * @function * * @description - * Deserializes a string in the JSON format. + * Deserializes a JSON string. * * @param {string} json JSON string to deserialize. - * @param {boolean} [useNative=false] Use native JSON parser if available + * @param {boolean} [useNative=false] Use native JSON parser, if available. * @returns {Object|Array|Date|string|number} Deserialized thingy. */ function fromJson(json, useNative) { diff --git a/src/directives.js b/src/directives.js index e0ac6c39..b3584a37 100644 --- a/src/directives.js +++ b/src/directives.js @@ -184,17 +184,19 @@ angularDirective("ng:controller", function(expression){ * @name angular.directive.ng:bind * * @description - * The `ng:bind` attribute tells Angular to replace the text content of the specified - * HTML element with the value of the given expression, and to update the text - * content whenever the expression's value changes. Usually, you would - * just write `{{ expression }}` and let Angular compile it into - * `<span ng:bind="expression"></span>` at bootstrap time. + * The `ng:bind` attribute tells Angular to replace the text content of the specified HTML element + * with the value of a given expression, and to update the text content when the value of that + * expression changes. + * + * Typically, you don't use `ng:bind` directly, but instead you use the double curly markup like + * `{{ expression }}` and let the Angular compiler transform it to + * `<span ng:bind="expression"></span>` when the template is compiled. * * @element ANY * @param {expression} expression {@link guide/dev_guide.expressions Expression} to evaluate. * * @example - * Enter a name in the Live Preview text box and watch the greeting below it change instantly. + * Enter a name in the Live Preview text box; the greeting below the text box changes instantly. <doc:example> <doc:source> Enter name: <input type="text" name="name" value="Whirled"> <br> @@ -372,42 +374,40 @@ var REMOVE_ATTRIBUTES = { 'multiple':'multiple' }; /** - * @workInProgress * @ngdoc directive * @name angular.directive.ng:bind-attr * * @description - * The `ng:bind-attr` attribute specifies that - * {@link guide/dev_guide.templates.databinding databindings} should be created between element - * attributes and given expressions. Unlike `ng:bind` the `ng:bind-attr` contains a JSON key value - * pairs representing which attributes need to be mapped to which - * {@link guide/dev_guide.expressions expressions}. - * - * You don't usually write the `ng:bind-attr` in the HTML since embedding - * <tt ng:non-bindable>{{expression}}</tt> into the attribute directly as the attribute value is - * preferred. The attributes get translated into `<span ng:bind-attr="{attr:expression}"/>` at - * compile time. - * - * This HTML snippet is preferred way of working with `ng:bind-attr` + * The `ng:bind-attr` attribute specifies that a + * {@link guide/dev_guide.templates.databinding databinding} should be created between a particular + * element attribute and a given expression. Unlike `ng:bind`, the `ng:bind-attr` contains one or + * more JSON key value pairs; each pair specifies an attribute and the + * {@link guide/dev_guide.expressions expression} to which it will be mapped. + * + * Instead of writing `ng:bind-attr` statements in your HTML, you can use double-curly markup to + * specify an <tt ng:non-bindable>{{expression}}</tt> for the value of an attribute. + * At compile time, the attribute is translated into an `<span ng:bind-attr="{attr:expression}"/>` + * + * The following HTML snippet shows how to specify `ng:bind-attr`: * <pre> * <a href="http://www.google.com/search?q={{query}}">Google</a> * </pre> * - * The above gets translated to bellow during bootstrap time. + * During compilation, the snippet gets translated to the following: * <pre> * <a ng:bind-attr='{"href":"http://www.google.com/search?q={{query}}"}'>Google</a> * </pre> * * @element ANY - * @param {string} attribute_json a JSON key-value pairs representing - * the attributes to replace. Each key matches the attribute + * @param {string} attribute_json one or more JSON key-value pairs representing + * the attributes to replace with expressions. Each key matches an attribute * which needs to be replaced. Each value is a text template of - * the attribute with embedded + * the attribute with the embedded * <tt ng:non-bindable>{{expression}}</tt>s. Any number of * key-value pairs can be specified. * * @example - * Try it here: enter text in text box and click Google. + * Enter a search string in the Live Preview text box and then click "Google". The search executes instantly. <doc:example> <doc:source> Google for: diff --git a/src/jqLite.js b/src/jqLite.js index 13ba5fd6..cb761294 100644 --- a/src/jqLite.js +++ b/src/jqLite.js @@ -5,28 +5,28 @@ ////////////////////////////////// /** - * @workInProgress * @ngdoc function * @name angular.element * @function * * @description - * Wraps a raw DOM element or HTML string as [jQuery](http://jquery.com) element. - * `angular.element` is either an alias for [jQuery](http://api.jquery.com/jQuery/) function if - * jQuery is loaded or a function that wraps the element or string in angular's jQuery lite - * implementation. + * Wraps a raw DOM element or HTML string as a [jQuery](http://jquery.com) element. + * `angular.element` can be either an alias for [jQuery](http://api.jquery.com/jQuery/) function, if + * jQuery is available, or a function that wraps the element or string in Angular's jQuery lite + * implementation (commonly referred to as jqLite). * - * Real jQuery always takes precedence (as long as it was loaded before `DOMContentEvent`) + * Real jQuery always takes precedence over jqLite, provided it was loaded before `DOMContentLoaded` + * event fired. * - * Angular's jQuery lite implementation is a tiny API-compatible subset of jQuery which allows - * angular to manipulate DOM. The jQuery lite implements only a subset of jQuery api, with the - * focus on the most commonly needed functionality and minimal footprint. For this reason only a - * limited number of jQuery methods, arguments and invocation styles are supported. + * jqLite is a tiny, API-compatible subset of jQuery that allows + * Angular to manipulate the DOM. jqLite implements only the most commonly needed functionality + * within a very small footprint, so only a subset of the jQuery API - methods, arguments and + * invocation styles - are supported. * - * Note: All element references in angular are always wrapped with jQuery (lite) and are never + * Note: All element references in Angular are always wrapped with jQuery or jqLite; they are never * raw DOM references. * - * ## Angular's jQuery lite implements these functions: + * ## Angular's jQuery lite provides the following methods: * * - [addClass()](http://api.jquery.com/addClass/) * - [after()](http://api.jquery.com/after/) @@ -48,10 +48,9 @@ * - [trigger()](http://api.jquery.com/trigger/) * - [eq()](http://api.jquery.com/eq/) * - * ## Additionally these methods extend the jQuery and are available in both jQuery and jQuery lite - * version: + * ## In addtion to the above, Angular privides an additional method to both jQuery and jQuery lite: * - *- `scope()` - retrieves the current angular scope of the element. + * - `scope()` - retrieves the current Angular scope of the element. * * @param {string|DOMElement} element HTML string or DOMElement to be wrapped into jQuery. * @returns {Object} jQuery object. diff --git a/src/markups.js b/src/markups.js index 3144bbb0..933d91f4 100644 --- a/src/markups.js +++ b/src/markups.js @@ -1,18 +1,17 @@ 'use strict'; /** - * @workInProgress * @ngdoc overview * @name angular.markup * @description * - * Angular markup transforms content of DOM elements or portions of this content into other text or - * DOM elements for further compilation. + * Angular markup transforms the content of DOM elements or portions of the content into other + * text or DOM elements for further compilation. * * Markup extensions do not themselves produce linking functions. Think of markup as a way to * produce shorthand for a {@link angular.widget widget} or a {@link angular.directive directive}. * - * The most prominent example of a markup in angular is the built-in double curly markup + * The most prominent example of a markup in Angular is the built-in, double curly markup * `{{expression}}`, which is shorthand for `<span ng:bind="expression"></span>`. * * Create custom markup like this: @@ -23,21 +22,24 @@ * }); * </pre> * - * For more information about angular markup, see {@link guide/dev_guide.compiler.markup - * Understanding Angular Markup} in the angular Developer Guide. + * For more information, see {@link guide/dev_guide.compiler.markup Understanding Angular Markup} + * in the Angular Developer Guide. */ /** - * @workInProgress * @ngdoc overview * @name angular.attrMarkup * @description * - * Attribute markup extends the angular compiler in a very similar way as {@link angular.markup} - * except that it allows you to modify the state of the attribute text rather than the content of a - * node. + * Attribute markup allows you to modify the state of an attribute's text. + * + * Attribute markup extends the Angular complier in a way similar to {@link angular.markup}, + * which allows you to modify the content of a node. + * + * The most prominent example of an attribute markup in Angular is the built-in double curly markup + * which is a shorthand for {@link angular.directive.ng:bind-attr ng:bind-attr}. * - * Create custom attribute markup like this: + * ## Example * * <pre> * angular.attrMarkup('newAttrMarkup', function(attrValue, attrName, element){ @@ -45,8 +47,8 @@ * }); * </pre> * - * For more information about angular attribute markup, see {@link guide/dev_guide.compiler.markup - * Understanding Angular Markup} in the angular Developer Guide. + * For more information about Angular attribute markup, see {@link guide/dev_guide.compiler.markup + * Understanding Angular Markup} in the Angular Developer Guide. */ function parseBindings(string) { |