Hopiu/angular.js
1
0
Fork 0
mirror of https://github.com/Hopiu/angular.js.git synced 2026-03-16 23:30:23 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs(API): various api doc fixes from Toni

Browse source
This commit is contained in:
Igor Minar 2011-09-01 00:06:09 -07:00
parent ff2cb86d5d
commit a5607e3061
6 changed files with 104 additions and 124 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

92
src/Angular.js
View file

@ -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

25
src/Injector.js
View file

@ -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) {

10
src/JSON.js
View file

@ -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) {

44
src/directives.js
View file

@ -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}.
* 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.
*
* 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.
* 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}"/>`
*
* This HTML snippet is preferred way of working with `ng:bind-attr`
* 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:

29
src/jqLite.js
View file

@ -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.

28
src/markups.js
View file

@ -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.
*
* Create custom attribute markup like this:
* 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}.
*
* ## 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) {