From 446f6b233fa8bd5bbdf2d6d9c980e3e23df52cd9 Mon Sep 17 00:00:00 2001 From: Toni Thompson Date: Thu, 18 Aug 2011 17:41:57 -0700 Subject: doc(API): various API documentation improvements --- src/Angular.js | 123 +++++++++++++++++++------------- src/apis.js | 206 +++++++++++++++++++++++++++++------------------------- src/directives.js | 71 ++++++++++--------- 3 files changed, 221 insertions(+), 179 deletions(-) (limited to 'src') diff --git a/src/Angular.js b/src/Angular.js index d5131c1f..1952b48e 100644 --- a/src/Angular.js +++ b/src/Angular.js @@ -44,8 +44,8 @@ var manualUppercase = function (s) { // String#toLowerCase and String#toUpperCase don't produce correct results in browsers with Turkish -// locale, for this reason we need to detect this case and redefine lowercase/uppercase methods with -// correct but slower alternatives. +// locale, for this reason we need to detect this case and redefine lowercase/uppercase methods +// with correct but slower alternatives. if ('i' !== 'I'.toLowerCase()) { lowercase = manualLowercase; uppercase = manualUppercase; @@ -118,10 +118,11 @@ var _undefined = undefined, * @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. 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. * * Note: this function was previously known as `angular.foreach`. * @@ -222,8 +223,8 @@ function nextUid() { * @function * * @description - * Extends the destination object `dst` by copying all of the properties from the `src` object(s) to - * `dst`. You can specify multiple `src` objects. + * 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). @@ -428,9 +429,13 @@ function isWindow(obj) { return obj && obj.document && obj.location && obj.alert && obj.setInterval; } -function isBoolean(value) { return typeof value == $boolean;} +function isBoolean(value) { return typeof value == $boolean; } function isTextNode(node) { return nodeName_(node) == '#text'; } -function trim(value) { return isString(value) ? value.replace(/^\s*/, '').replace(/\s*$/, '') : value; } + +function trim(value) { + return isString(value) ? value.replace(/^\s*/, '').replace(/\s*$/, '') : value; +} + function isElement(node) { return node && (node.nodeName // we are a direct element @@ -451,10 +456,12 @@ function makeMap(str){ /** - * HTML class which is the only class which can be used in ng:bind to inline HTML for security reasons. + * HTML class which is the only class which can be used in ng:bind to inline HTML for security + * reasons. + * * @constructor * @param html raw (unsafe) html - * @param {string=} option if set to 'usafe' then get method will return raw (unsafe/unsanitized) html + * @param {string=} option If set to 'usafe', get method will return raw (unsafe/unsanitized) html */ function HTML(html, option) { this.html = html; @@ -470,7 +477,8 @@ function HTML(html, option) { if (msie < 9) { nodeName_ = function(element) { element = element.nodeName ? element : element[0]; - return (element.scopeName && element.scopeName != 'HTML' ) ? uppercase(element.scopeName + ':' + element.nodeName) : element.nodeName; + return (element.scopeName && element.scopeName != 'HTML') + ? uppercase(element.scopeName + ':' + element.nodeName) : element.nodeName; }; } else { nodeName_ = function(element) { @@ -500,26 +508,35 @@ function map(obj, iterator, context) { * @function * * @description - * Determines the number of elements in an array, number of properties of an object or string - * length. + * Determines the number of elements in an array, the number of properties an object has, or + * the length of a string. * - * Note: this function is used to augment the Object type in angular expressions. See - * {@link angular.Object} for more info. + * Note: This function is used to augment the Object type in Angular expressions. See + * {@link angular.Object} for more information about Angular arrays. * - * @param {Object|Array|string} obj Object, array or string to inspect. + * @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. * * @example * * - * Number of items in array: {{ [1,2].$size() }}
- * Number of items in object: {{ {a:1, b:2, c:3}.$size() }}
+ * + *
+ * Number of items in array: {{ [1,2].$size() }}
+ * Number of items in object: {{ {a:1, b:2, c:3}.$size() }}
+ * String length: {{fooStringLength}} + *
* * * it('should print correct sizes for an array and an object', function() { * expect(binding('[1,2].$size()')).toBe('2'); * expect(binding('{a:1, b:2, c:3}.$size()')).toBe('3'); + * expect(binding('fooStringLength')).toBe('3'); * }); * * @@ -581,24 +598,21 @@ function isLeafNode (node) { * @function * * @description - * Creates a deep copy of `source`. + * Creates a deep copy of `source`, which should be an object or an array. * - * If `source` is an object or an array, all of its members will be copied into the `destination` - * object. + * * If no destination is supplied, a copy of the object or array is created. + * * If a destination is provided, all of its elements (for array) or properties (for objects) + * are deleted and then all elements/properties from the source are copied to it. + * * If `source` is not an object or array, `source` is returned. * - * If `destination` is not provided and `source` is an object or an array, a copy is created & - * returned, otherwise the `source` is returned. + * Note: this function is used to augment the Object type in Angular expressions. See + * {@link angular.Array} for more information about Angular arrays. * - * If `destination` is provided, all of its properties will be deleted. - * - * Note: this function is used to augment the Object type in angular expressions. See - * {@link angular.Object} for more info. - * - * @param {*} source The source to be used to make a copy. - * Can be any type including primitives, `null` and `undefined`. - * @param {(Object|Array)=} destination Optional destination into which the source is copied. If + * @param {*} source The source that will be used to make a copy. + * Can be any type, including primitives, `null`, and `undefined`. + * @param {(Object|Array)=} destination Destination into which the source is copied. If * provided, must be of the same type as `source`. - * @returns {*} The copy or updated `destination` if `destination` was specified. + * @returns {*} The copy or updated `destination`, if `destination` was specified. * * @example * @@ -660,7 +674,6 @@ function copy(source, destination){ } /** - * @workInProgress * @ngdoc function * @name angular.equals * @function @@ -675,16 +688,19 @@ function copy(source, destination){ * @function * * @description - * Determines if two objects or value are equivalent. + * Determines if two objects or two values are equivalent. Supports value types, arrays and + * objects. * - * To be equivalent, they must pass `===` comparison or be of the same type and have all their - * properties pass `===` comparison. During property comparision properties of `function` type and - * properties with name starting with `$` are ignored. + * Two objects or values are considered equivalent if at least one of the following is true: * - * Supports values types, arrays and objects. + * * Both objects or values pass `===` comparison. + * * Both objects or values are of the same type and all of their properties pass `===` comparison. * - * Note: this function is used to augment the Object type in angular expressions. See - * {@link angular.Object} for more info. + * During a property comparision, properties of `function` type and properties with names + * that begin with `$` are ignored. + * + * Note: This function is used to augment the Object type in Angular expressions. See + * {@link angular.Array} for more information about Angular arrays. * * @param {*} o1 Object or value to compare. * @param {*} o2 Object or value to compare. @@ -732,7 +748,9 @@ function equals(o1, o2) { } else { keySet = {}; for(key in o1) { - if (key.charAt(0) !== '$' && !isFunction(o1[key]) && !equals(o1[key], o2[key])) return false; + if (key.charAt(0) !== '$' && !isFunction(o1[key]) && !equals(o1[key], o2[key])) { + return false; + } keySet[key] = true; } for(key in o2) { @@ -802,7 +820,9 @@ function sliceArgs(args, startIndex) { * @function * * @description - * Returns a function which calls function `fn` bound to `self` (`self` becomes the `this` for `fn`). + * 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). * @@ -826,7 +846,8 @@ 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 and so they can not be bound + // (but they don't need to be) return fn; } } @@ -928,7 +949,6 @@ function encodeUriQuery(val, pctEncodeSpaces) { /** - * @workInProgress * @ngdoc directive * @name angular.directive.ng:autobind * @element script @@ -938,14 +958,17 @@ function encodeUriQuery(val, pctEncodeSpaces) { * @TODO rename to ng:autobind to ng:autoboot * * @description + * Technically, ng:autobind is not a directive; it is an Angular bootstrap parameter that can act + * as a directive. It must exist in the script used to boot Angular and can be used only one time. + * For details on bootstrapping Angular, see {@link guide/dev_guide.bootstrap Initializing Angular} + * in the Angular Developer Guide. * - * `ng:autobind` with no parameters tells angular to compile and manage the whole page. + * `ng:autobind` with no parameters tells Angular to compile and manage the whole page. * - * `ng:autobind="[root element ID]"` tells angular to compile and manage part of the docucment, + * `ng:autobind="[root element ID]"` tells Angular to compile and manage part of the document, * starting at "root element ID". * - * For details on bootstrapping angular, see {@link guide/dev_guide.bootstrap Initializing Angular} - * in the Angular Developer Guide. + */ function angularInit(config, document){ var autobind = config.autobind; diff --git a/src/apis.js b/src/apis.js index 10cccacf..9f081012 100644 --- a/src/apis.js +++ b/src/apis.js @@ -23,18 +23,20 @@ var angularGlobal = { * A namespace for utility functions used to work with JavaScript objects. These functions are * exposed in two ways: * - * __* Angular expressions:__ Functions are bound to all objects and augment the Object type. The - * names of these methods are prefixed with the '$' character in order to minimize naming collisions. - * To call a method, invoke the function without the first argument, e.g, `myObject.$foo(param2)`. + * * __Angular expressions:__ Functions are bound to all objects and augment the Object type. + * The names of these methods are prefixed with the '$' character in order to minimize naming + * collisions. To call a method, invoke the function without the first argument, for example, + * `myObject.$foo(param2)`. * - * __* JavaScript code:__ Functions don't augment the Object type and must be invoked as functions of - * `angular.Object` as `angular.Object.foo(myObject, param2)`. + * * __JavaScript code:__ Functions don't augment the Object type and must be invoked as functions + * of `angular.Object` as `angular.Object.foo(myObject, param2)`. * - * * {@link angular.Object.copy angular.Object.copy()} - Creates a deep copy of the source parameter - * * {@link angular.Object.equals angular.Object.equals()} - Determines if two objects or values are - * equivalent - * * {@link angular.Object.size angular.Object.size()} - Determines the number of elements in - * strings, arrays, and objects. + * * {@link angular.Object.copy angular.Object.copy()} - Creates a deep copy of the source + * parameter. + * * {@link angular.Object.equals angular.Object.equals()} - Determines if two objects or values + * are equivalent. + * * {@link angular.Object.size angular.Object.size()} - Determines the number of elements in + * strings, arrays, and objects. */ var angularCollection = { 'copy': copy, @@ -54,28 +56,30 @@ var angularObject = { * * These functions are exposed in two ways: * - * * __Angular expressions:__ Functions are bound to the Array objects and augment the Array type as - * array methods. The names of these methods are prefixed with $ character to minimize naming - * collisions. To call a method, invoke myArrayObject.$foo(params). + * * __Angular expressions:__ Functions are bound to the Array objects and augment the Array type + * as array methods. The names of these methods are prefixed with the `$` character to minimize + * naming collisions. To call a method, invoke myArrayObject.$foo(params). * * Because Array type is a subtype of the Object type, all angular.Object functions augment - * theArray type in angular expressions as well. + * the Array type in Angular expressions as well. * - * * __JavaScript code:__ Functions don't augment the Array type and must be invoked as functions of - * `angular.Array` as `angular.Array.foo(myArrayObject, params)`. + * * __JavaScript code:__ Functions do nor augment the Array type and must be invoked as functions + * of `angular.Array` as `angular.Array.foo(myArrayObject, params)`. * - * The following APIs are built-in to the angular Array object: + * The following APIs are built in to the Angular Array object: * * * {@link angular.Array.add angular.Array.add()} - Optionally adds a new element to an array. * * {@link angular.Array.count angular.Array.count()} - Determines the number of elements in an - * array. - * * {@link angular.Array.filter angular.Array.filter()} - Returns a subset of items as a new array. - * * {@link angular.Array.indexOf angular.Array.indexOf()} - Determines the index of an array value. - * * {@link angular.Array.limitTo angular.Array.limitTo()} - Creates a new array off the front or - * back of an existing array. - * * {@link angular.Array.orderBy angular.Array.orderBy()} - Orders array elements - * * {@link angular.Array.remove angular.Array.remove()} - Removes array elements - * * {@link angular.Array.sum angular.Array.sum()} - Sums the number elements in an array + * array. + * * {@link angular.Array.filter angular.Array.filter()} - Returns the subset of elements specified + * in the filter as a new array. + * * {@link angular.Array.indexOf angular.Array.indexOf()} - Determines the index of an array + * value. + * * {@link angular.Array.limitTo angular.Array.limitTo()} - Creates a sub-array of an existing + * array. + * * {@link angular.Array.orderBy angular.Array.orderBy()} - Orders array elements. + * * {@link angular.Array.remove angular.Array.remove()} - Removes array elements. + * * {@link angular.Array.sum angular.Array.sum()} - Sums the numbers in an array. */ var angularArray = { @@ -86,14 +90,15 @@ var angularArray = { * @function * * @description - * Determines the index of `value` in `array`. + * Determines the index of a `value` in an `array`. * - * Note: this function is used to augment the `Array` type in angular expressions. See - * {@link angular.Array} for more info. + * Note: This function is used to augment the `Array` type in Angular expressions. See + * {@link angular.Array} for more information about Angular arrays. * * @param {Array} array Array to search. * @param {*} value Value to search for. - * @returns {number} The position of the element in `array`. The position is 0-based. `-1` is returned if the value can't be found. + * @returns {number} The position of the element in `array`. The position is 0-based. + * If the value cannot be found, `-1` is returned. * * @example @@ -126,38 +131,39 @@ var angularArray = { * @function * * @description - * This function calculates the sum of all numbers in `array`. If the `expressions` is supplied, - * it is evaluated once for each element in `array` and then the sum of these values is returned. + * The `sum` function calculates the sum of all numbers in an `array`. If an `expression` is + * supplied, `sum` evaluates each element in the `array` with the expression and then returns + * the sum of the calculated values. * - * Note: this function is used to augment the `Array` type in angular expressions. See - * {@link angular.Array} for more info. + * Note: This function is used to augment the `Array` type in Angular expressions. See + * {@link angular.Array} for more info about Angular arrays. * * @param {Array} array The source array. - * @param {(string|function())=} expression Angular expression or a function to be evaluated for each - * element in `array`. The array element becomes the `this` during the evaluation. + * @param {(string|function())=} expression Angular expression or a function to be evaluated for + * each element in `array`. The array element becomes the `this` during the evaluation. * @returns {number} Sum of items in the array. * * @example - - - - - - - - - - - - - - - - -
QtyDescriptionCostTotal
{{item.qty * item.cost | currency}}[X]
add itemTotal:{{invoice.items.$sum('qty*cost') | currency}}
- - + + + + + + + + + + + + + + + + +
QtyDescriptionCostTotal
{{item.qty * item.cost | currency}}[X]
add itemTotal:{{invoice.items.$sum('qty*cost') | currency}}
+ + //TODO: these specs are lame because I had to work around issues #164 and #167 it('should initialize and calculate the totals', function() { expect(repeater('.doc-example-live table tr', 'item in invoice.items').count()).toBe(3); @@ -176,7 +182,7 @@ var angularArray = { toEqual(['$2,000.00']); expect(binding("invoice.items.$sum('qty*cost')")).toBe('$2,099.50'); }); - + */ 'sum':function(array, expression) { @@ -202,8 +208,8 @@ var angularArray = { * {@link angular.Array.indexOf indexOf} function on the `array` and only the first instance of * the element will be removed. * - * Note: this function is used to augment the `Array` type in angular expressions. See - * {@link angular.Array} for more info. + * Note: This function is used to augment the `Array` type in Angular expressions. See + * {@link angular.Array} for more information about Angular arrays. * * @param {Array} array Array from which an element should be removed. * @param {*} value Element to be removed. @@ -258,8 +264,8 @@ var angularArray = { * @description * Selects a subset of items from `array` and returns it as a new array. * - * Note: this function is used to augment the `Array` type in angular expressions. See - * {@link angular.Array} for more info. + * Note: This function is used to augment the `Array` type in Angular expressions. See + * {@link angular.Array} for more information about Angular arrays. * * @param {Array} array The source array. * @param {string|Object|function()} expression The predicate to be used for selecting items from @@ -412,28 +418,28 @@ var angularArray = { /** - * @workInProgress * @ngdoc function * @name angular.Array.add * @function * * @description - * `add` is a function similar to JavaScript's `Array#push` method, in that it appends a new - * element to an array. The difference is that the value being added is optional and defaults to - * an empty object. + * The `add` function in Angualar is similar to JavaScript's `Array#push` method in that it + * appends a new element to an array. Angular's function differs from the JavaScript method in + * that specifying a value for the function is optional and the default for the function is an + * empty object. * - * Note: this function is used to augment the `Array` type in angular expressions. See - * {@link angular.Array} for more info. + * Note: This function is used to augment the `Array` type in Angular expressions. See + * {@link angular.Array} for more information about Angular arrays. * - * @param {Array} array The array expand. - * @param {*=} [value={}] The value to be added. + * @param {Array} array The array to be expanded. + * @param {*=} [value={}] The value to be appended. * @returns {Array} The expanded array. * * @TODO simplify the example. * * @example - * This example shows how an initially empty array can be filled with objects created from user - * input via the `$add` method. + * This example shows how you can use the `$add` method to populate an initially empty array + * with objects created from user input. [add empty] @@ -493,17 +499,18 @@ var angularArray = { * @function * * @description - * Determines the number of elements in an array. Optionally it will count only those elements - * for which the `condition` evaluates to `true`. + * Determines the number of elements in an array. Provides an option for counting only those + * elements for which a specified `condition` evaluates to `true`. * - * Note: this function is used to augment the `Array` type in angular expressions. See - * {@link angular.Array} for more info. + * Note: This function is used to augment the `Array` type in Angular expressions. See + * {@link angular.Array} for more information about Angular arrays. * - * @param {Array} array The array to count elements in. - * @param {(function()|string)=} condition A function to be evaluated or angular expression to be - * compiled and evaluated. The element that is currently being iterated over, is exposed to - * the `condition` as `this`. - * @returns {number} Number of elements in the array (for which the condition evaluates to true). + * @param {Array} array The array containing the elements to be counted. + * @param {(function()|string)=} condition A function to be evaluated or + * an Angular expression to be compiled and evaluated. The element being + * iterated over is exposed to the `condition` as `this`. + * @returns {number} Number of elements in the array. If a `condition` is specified, returns + * the number of elements whose `condition` evaluates to `true`. * * @example @@ -518,7 +525,8 @@ var angularArray = {

Number of items which have one point: {{ items.$count('points==1') }}

-

Number of items which have more than one point: {{items.$count('points>1')}}

+

Number of items which have more than one point: + {{items.$count('points>1')}}

 it('should calculate counts', function() { @@ -552,10 +560,10 @@ var angularArray = { * @function * * @description - * Orders `array` by the `expression` predicate. + * Orders a specified `array` by the `expression` predicate. * - * Note: this function is used to augment the `Array` type in angular expressions. See - * {@link angular.Array} for more info. + * Note: this function is used to augment the `Array` type in Angular expressions. See + * {@link angular.Array} for more informaton about Angular arrays. * * @param {Array} array The array to sort. * @param {function(*)|string|Array.<(function(*)|string)>} expression A predicate to be @@ -563,13 +571,13 @@ var angularArray = { * * Can be one of: * - * - `function`: getter function. The result of this function will be sorted using the - * `<`, `=`, `>` operator - * - `string`: angular expression which evaluates to an object to order by, such as 'name' to - * sort by a property called 'name'. Optionally prefixed with `+` or `-` to control ascending - * or descending sort order (e.g. +name or -name). - * - `Array`: array of function or string predicates, such that a first predicate in the array - * is used for sorting, but when the items are equivalent next predicate is used. + * - `function`: Getter function. The result of this function will be sorted using the + * `<`, `=`, `>` operator. + * - `string`: An Angular expression which evaluates to an object to order by, such as 'name' + * to sort by a property called 'name'. Optionally prefixed with `+` or `-` to control + * ascending or descending sort order (for example, +name or -name). + * - `Array`: An array of function or string predicates. The first predicate in the array + * is used for sorting, but when two items are equivalent, the next predicate is used. * * @param {boolean=} reverse Reverse the order the array. * @returns {Array} Sorted copy of the source array. @@ -678,16 +686,18 @@ var angularArray = { * @function * * @description - * Creates a new array containing only the first, or last `limit` number of elements of the - * source `array`. + * Creates a new array containing only a specified number of elements in an array. The elements + * are taken from either the beginning or the end of the source array, as specified by the + * value and sign (positive or negative) of `limit`. * - * Note: this function is used to augment the `Array` type in angular expressions. See - * {@link angular.Array} for more info. + * Note: This function is used to augment the `Array` type in Angular expressions. See + * {@link angular.Array} for more information about Angular arrays. * * @param {Array} array Source array to be limited. - * @param {string|Number} limit The length of the returned array. If the number is positive, the - * first `limit` items from the source array will be copied, if the number is negative, the - * last `limit` items will be copied. + * @param {string|Number} limit The length of the returned array. If the `limit` number is + * positive, `limit` number of items from the beginning of the source array are copied. + * If the number is negative, `limit` number of items from the end of the source array are + * copied. * @returns {Array} A new sub-array of length `limit`. * * @example @@ -761,7 +771,9 @@ var angularString = { }, /** - * Tries to convert input to date and if successful returns the date, otherwise returns the input. + * Tries to convert input to date and if successful returns the date, otherwise returns the + * input. + * * @param {string} string * @return {(Date|string)} */ diff --git a/src/directives.js b/src/directives.js index 7edbbd6f..2ca7b79b 100644 --- a/src/directives.js +++ b/src/directives.js @@ -1,44 +1,46 @@ 'use strict'; /** - * @workInProgress * @ngdoc overview * @name angular.directive * @description * - * Custom attributes for DOM elements. Directives modify the behavior of the element they are - * specified in, but are not intended to add elements to the DOM as are - * {@link angular.widget widgets}. + * Angular directives create custom attributes for DOM elements. A directive can modify the + * behavior of the element in which it is specified. Do not use directives to add elements to the + * DOM; instead, use {@link angular.widget widgets} to add DOM elements. * - * Following is the list of built-in angular directives: + * Following is the list of built-in Angular directives: * - * * {@link angular.directive.ng:bind ng:bind} - Creates a data-binding between HTML text value and - * data model. - * * {@link angular.directive.ng:bind-attr ng:bind-attr} - Creates a data-binding as in `ng:bind`, - * but uses JSON key / value pairs. - * * {@link angular.directive.ng:bind-template ng:bind-template} - Replaces text value of an element - * with a specified template. + * * {@link angular.directive.ng:autobind ng:autobind} - An Angular bootstrap parameter that can + * act as a directive. + * * {@link angular.directive.ng:bind ng:bind} - Creates a data-binding between an HTML text value + * and a data model. + * * {@link angular.directive.ng:bind-attr ng:bind-attr} - Creates a data-binding in a way similar + * to `ng:bind`, but uses JSON key / value pairs to do so. + * * {@link angular.directive.ng:bind-template ng:bind-template} - Replaces the text value of an + * element with a specified template. * * {@link angular.directive.ng:change ng:change} - Executes an expression when the value of an * input widget changes. - * * {@link angular.directive.ng:class ng:class} - Conditionally set CSS class on an element. + * * {@link angular.directive.ng:class ng:class} - Conditionally set a CSS class on an element. * * {@link angular.directive.ng:class-even ng:class-even} - Like `ng:class`, but works in * conjunction with {@link angular.widget.@ng:repeat} to affect even rows in a collection. * * {@link angular.directive.ng:class-odd ng:class-odd} - Like `ng:class`, but works with {@link * angular.widget.@ng:repeat} to affect odd rows. - * * {@link angular.directive.ng:click ng:click} - Executes custom behavior when element is clicked. + * * {@link angular.directive.ng:click ng:click} - Executes custom behavior when an element is + * clicked. * * {@link angular.directive.ng:controller ng:controller} - Creates a scope object linked to the * DOM element and assigns behavior to the scope. * * {@link angular.directive.ng:hide ng:hide} - Conditionally hides a portion of HTML. - * * {@link angular.directive.ng:href ng:href} - Places an href in the angular namespace. + * * {@link angular.directive.ng:href ng:href} - Places an href in the Angular namespace. * * {@link angular.directive.ng:init} - Initialization tasks run before a template is executed. * * {@link angular.directive.ng:show ng:show} - Conditionally displays a portion of HTML. - * * {@link angular.directive.ng:src ng:src} - Places a `src` attribute into the angular namespace. + * * {@link angular.directive.ng:src ng:src} - Places a `src` attribute into the Angular namespace. * * {@link angular.directive.ng:style ng:style} - Conditionally set CSS styles on an element. - * * {@link angular.directive.ng:submit} - Binds angular expressions to `onSubmit` events. + * * {@link angular.directive.ng:submit} - Binds Angular expressions to `onSubmit` events. * - * For more information about how angular directives work, and how to create your own directives, - * see {@link guide/dev_guide.compiler.directives Understanding Angular Directives} in the angular - * Developer Guide. + * For more information about how Angular directives work, and to learn how to create your own + * directives, see {@link guide/dev_guide.compiler.directives Understanding Angular Directives} in + * the Angular Developer Guide. */ /** @@ -151,12 +153,17 @@ angularDirective("ng:init", function(expression){ it('should check controller', function(){ expect(element('.doc-example-live div>:input').val()).toBe('John Smith'); - expect(element('.doc-example-live li[ng\\:repeat-index="0"] input').val()).toBe('408 555 1212'); - expect(element('.doc-example-live li[ng\\:repeat-index="1"] input').val()).toBe('john.smith@example.org'); + expect(element('.doc-example-live li[ng\\:repeat-index="0"] input').val()) + .toBe('408 555 1212'); + expect(element('.doc-example-live li[ng\\:repeat-index="1"] input').val()) + .toBe('john.smith@example.org'); + element('.doc-example-live li:first a:contains("clear")').click(); expect(element('.doc-example-live li:first input').val()).toBe(''); + element('.doc-example-live li:last a:contains("add")').click(); - expect(element('.doc-example-live li[ng\\:repeat-index="2"] input').val()).toBe('yourname@example.org'); + expect(element('.doc-example-live li[ng\\:repeat-index="2"] input').val()) + .toBe('yourname@example.org'); }); @@ -173,22 +180,21 @@ angularDirective("ng:controller", function(expression){ }); /** - * @workInProgress * @ngdoc directive * @name angular.directive.ng:bind * * @description - * The `ng:bind` attribute asks angular to replace the text content of this - * HTML element with the value of the given expression, and to keep the text - * content up to date when the expression's value changes. Usually you would - * just write `{{ expression }}` and let angular compile it into + * 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 * `` at bootstrap time. * * @element ANY - * @param {expression} expression {@link guide/dev_guide.expressions Expression} to eval. + * @param {expression} expression {@link guide/dev_guide.expressions Expression} to evaluate. * * @example - * You can try it right here: enter text in the text box and watch the greeting change. + * Enter a name in the Live Preview text box and watch the greeting below it change instantly. Enter name:
@@ -227,8 +233,8 @@ angularDirective("ng:bind", function(expression, element){ delete scope.$element; } } - // If we are HTML than save the raw HTML data so that we don't - // recompute sanitization since it is expensive. + // If we are HTML, then save the raw HTML data so that we don't + // recompute sanitization since that is expensive. // TODO: turn this into a more generic way to compute this if ((isHtml = (value instanceof HTML))) value = (html = value).html; @@ -458,7 +464,8 @@ angularDirective("ng:bind-attr", function(expression){ * element is clicked. * * @element ANY - * @param {expression} expression {@link guide/dev_guide.expressions Expression} to eval upon click. + * @param {expression} expression {@link guide/dev_guide.expressions Expression} to evaluate upon + * click. * * @example -- cgit v1.2.3