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(scope): clean up grammar and improve clarity

Browse source 
Some typos fixed and grammar improved:
- withing -> within
- life-cycle -> life cycle
- extraneous spaces
- grammar mistakes
- missing commas
- reworded unclear statements

Closes #3920
This commit is contained in:
Sam Dornan 2013-09-07 12:29:49 -07:00 committed by Pete Bacon Darwin
parent c0db11c607
commit f86395aadf
1 changed files with 27 additions and 28 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

55
src/ng/rootScope.js
View file

@ -56,7 +56,7 @@
*
* Every application has a single root {@link ng.$rootScope.Scope scope}.
* All other scopes are child scopes of the root scope. Scopes provide mechanism for watching the model and provide
* event processing life-cycle. See {@link guide/scope developer guide on scopes}.
* event processing life cycle. See {@link guide/scope developer guide on scopes}.
*/
function $RootScopeProvider(){
var TTL = 10;
@ -152,9 +152,9 @@ function $RootScopeProvider(){
* the scope and its child scopes to be permanently detached from the parent and thus stop
* participating in model change detection and listener notification by invoking.
*
* @param {boolean} isolate if true then the scope does not prototypically inherit from the
* @param {boolean} isolate If true, then the scope does not prototypically inherit from the
* parent scope. The scope is isolated, as it can not see parent scope properties.
* When creating widgets it is useful for the widget to not accidentally read parent
* When creating widgets, it is useful for the widget to not accidentally read parent
* state.
*
* @returns {Object} The newly created child scope.
@ -167,12 +167,12 @@ function $RootScopeProvider(){
if (isolate) {
child = new Scope();
child.$root = this.$root;
// ensure that there is just one async queue per $rootScope and it's children
// ensure that there is just one async queue per $rootScope and its children
child.$$asyncQueue = this.$$asyncQueue;
child.$$postDigestQueue = this.$$postDigestQueue;
} else {
Child = function() {}; // should be anonymous; This is so that when the minifier munges
// the name it does not become random set of chars. These will then show up as class
// the name it does not become random set of chars. This will then show up as class
// name in the debugger.
Child.prototype = this;
child = new Child();
@ -202,7 +202,7 @@ function $RootScopeProvider(){
* Registers a `listener` callback to be executed whenever the `watchExpression` changes.
*
* - The `watchExpression` is called on every call to {@link ng.$rootScope.Scope#$digest $digest()} and
* should return the value which will be watched. (Since {@link ng.$rootScope.Scope#$digest $digest()}
* should return the value that will be watched. (Since {@link ng.$rootScope.Scope#$digest $digest()}
* reruns when it detects changes the `watchExpression` can execute multiple times per
* {@link ng.$rootScope.Scope#$digest $digest()} and should be idempotent.)
* - The `listener` is called only when the value from the current `watchExpression` and the
@ -313,13 +313,13 @@ function $RootScopeProvider(){
*
* @description
* Shallow watches the properties of an object and fires whenever any of the properties change
* (for arrays this implies watching the array items, for object maps this implies watching the properties).
* If a change is detected the `listener` callback is fired.
* (for arrays, this implies watching the array items; for object maps, this implies watching the properties).
* If a change is detected, the `listener` callback is fired.
*
* - The `obj` collection is observed via standard $watch operation and is examined on every call to $digest() to
* see if any items have been added, removed, or moved.
* - The `listener` is called whenever anything within the `obj` has changed. Examples include adding new items
* into the object or array, removing and moving items around.
* - The `listener` is called whenever anything within the `obj` has changed. Examples include adding, removing,
* and moving items belonging to an object or array.
*
*
* # Example
@ -356,8 +356,8 @@ function $RootScopeProvider(){
* `oldCollection` object is a copy of the former collection data.
* The `scope` refers to the current scope.
*
* @returns {function()} Returns a de-registration function for this listener. When the de-registration function is executed
* then the internal watch operation is terminated.
* @returns {function()} Returns a de-registration function for this listener. When the de-registration function
* is executed, the internal watch operation is terminated.
*/
$watchCollection: function(obj, listener) {
var self = this;
@ -458,18 +458,17 @@ function $RootScopeProvider(){
* firing. This means that it is possible to get into an infinite loop. This function will throw
* `'Maximum iteration limit exceeded.'` if the number of iterations exceeds 10.
*
* Usually you don't call `$digest()` directly in
* Usually, you don't call `$digest()` directly in
* {@link ng.directive:ngController controllers} or in
* {@link ng.$compileProvider#directive directives}.
* Instead a call to {@link ng.$rootScope.Scope#$apply $apply()} (typically from within a
* {@link ng.$compileProvider#directive directives}) will force a `$digest()`.
* Instead, you should call {@link ng.$rootScope.Scope#$apply $apply()} (typically from within a
* {@link ng.$compileProvider#directive directives}), which will force a `$digest()`.
*
* If you want to be notified whenever `$digest()` is called,
* you can register a `watchExpression` function with {@link ng.$rootScope.Scope#$watch $watch()}
* you can register a `watchExpression` function with {@link ng.$rootScope.Scope#$watch $watch()}
* with no `listener`.
*
* You may have a need to call `$digest()` from within unit-tests, to simulate the scope
* life-cycle.
* In unit tests, you may need to call `$digest()` to simulate the scope life cycle.
*
* # Example
* <pre>
@ -610,8 +609,8 @@ function $RootScopeProvider(){
* {@link ng.directive:ngRepeat ngRepeat} for managing the
* unrolling of the loop.
*
* Just before a scope is destroyed a `$destroy` event is broadcasted on this scope.
* Application code can register a `$destroy` event handler that will give it chance to
* Just before a scope is destroyed, a `$destroy` event is broadcasted on this scope.
* Application code can register a `$destroy` event handler that will give it a chance to
* perform any necessary cleanup.
*
* Note that, in AngularJS, there is also a `$destroy` jQuery event, which can be used to
@ -643,7 +642,7 @@ function $RootScopeProvider(){
* @function
*
* @description
* Executes the `expression` on the current scope returning the result. Any exceptions in the
* Executes the `expression` on the current scope and returns the result. Any exceptions in the
* expression are propagated (uncaught). This is useful when evaluating Angular expressions.
*
* # Example
@ -678,19 +677,19 @@ function $RootScopeProvider(){
*
* The `$evalAsync` makes no guarantees as to when the `expression` will be executed, only that:
*
* - it will execute after the function that schedule the evaluation is done running (preferably before DOM rendering).
* - it will execute after the function that scheduled the evaluation (preferably before DOM rendering).
* - at least one {@link ng.$rootScope.Scope#$digest $digest cycle} will be performed after `expression` execution.
*
* Any exceptions from the execution of the expression are forwarded to the
* {@link ng.$exceptionHandler $exceptionHandler} service.
*
* __Note:__ if this function is called outside of `$digest` cycle, a new $digest cycle will be scheduled.
* It is however encouraged to always call code that changes the model from withing an `$apply` call.
* __Note:__ if this function is called outside of a `$digest` cycle, a new `$digest` cycle will be scheduled.
* However, it is encouraged to always call code that changes the model from within an `$apply` call.
* That includes code evaluated via `$evalAsync`.
*
* @param {(string|function())=} expression An angular expression to be executed.
*
* - `string`: execute using the rules as defined in {@link guide/expression expression}.
* - `string`: execute using the rules as defined in {@link guide/expression expression}.
* - `function(scope)`: execute the function with the current `scope` parameter.
*
*/
@ -721,7 +720,7 @@ function $RootScopeProvider(){
* @description
* `$apply()` is used to execute an expression in angular from outside of the angular framework.
* (For example from browser DOM events, setTimeout, XHR or third party libraries).
* Because we are calling into the angular framework we need to perform proper scope life-cycle
* Because we are calling into the angular framework we need to perform proper scope life cycle
* of {@link ng.$exceptionHandler exception handling},
* {@link ng.$rootScope.Scope#$digest executing watches}.
*
@ -790,7 +789,7 @@ function $RootScopeProvider(){
*
* - `targetScope` - `{Scope}`: the scope on which the event was `$emit`-ed or `$broadcast`-ed.
* - `currentScope` - `{Scope}`: the current scope which is handling the event.
* - `name` - `{string}`: Name of the event.
* - `name` - `{string}`: name of the event.
* - `stopPropagation` - `{function=}`: calling `stopPropagation` function will cancel further event
* propagation (available only for events that were `$emit`-ed).
* - `preventDefault` - `{function}`: calling `preventDefault` sets `defaultPrevented` flag to true.
@ -833,7 +832,7 @@ function $RootScopeProvider(){
*
* @param {string} name Event name to emit.
* @param {...*} args Optional set of arguments which will be passed onto the event listeners.
* @return {Object} Event object, see {@link ng.$rootScope.Scope#$on}
* @return {Object} Event object (see {@link ng.$rootScope.Scope#$on}).
*/
$emit: function(name, args) {
var empty = [],