Skip to content
This repository was archived by the owner on Apr 12, 2024. It is now read-only.

docs($rootScope.Scope): clarify $watchGroup "oldValues" argument #16005

Merged
merged 1 commit into from
Jun 29, 2017
Merged

docs($rootScope.Scope): clarify $watchGroup "oldValues" argument #16005

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 34 additions & 1 deletion src/ng/rootScope.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -449,6 +449,12 @@ function $RootScopeProvider() {
* values are examined for changes on every call to `$digest`.
* - The `listener` is called whenever any expression in the `watchExpressions` array changes.
*
* `$watchGroup` is more performant than watching each expression individually, and should be
* used when the listener does not need to know which expression has changed.
* If the listener needs to know which expression has changed,
* {@link ng.$rootScope.Scope#$watch $watch()} or
* {@link ng.$rootScope.Scope#$watchCollection $watchCollection()} should be used.
*
* @param {Array.<string|Function(scope)>} watchExpressions Array of expressions that will be individually
* watched using {@link ng.$rootScope.Scope#$watch $watch()}
*
Expand All @@ -457,7 +463,34 @@ function $RootScopeProvider() {
* The `newValues` array contains the current values of the `watchExpressions`, with the indexes matching
* those of `watchExpression`
* and the `oldValues` array contains the previous values of the `watchExpressions`, with the indexes matching
* those of `watchExpression`
* those of `watchExpression`.
*
* Note that `newValues` and `oldValues` reflect the differences in each **individual**
* expression, and not the difference of the values between each call of the listener.
* That means the difference between `newValues` and `oldValues` cannot be used to determine
* which expression has changed / remained stable:
*
* ```js
*
* $scope.$watchGroup(['v1', 'v2'], function(newValues, oldValues) {
* console.log(newValues, oldValues);
* });
*
* // newValues, oldValues initially
* // [undefined, undefined], [undefined, undefined]
*
* $scope.v1 = 'a';
* $scope.v2 = 'a';
*
* // ['a', 'a'], [undefined, undefined]
*
* $scope.v2 = 'b'
*
* // v1 hasn't changed since it became `'a'`, therefore its oldValue is still `undefined`
* // ['a', 'b'], [undefined, 'a']
*
* ```
*
* The `scope` refers to the current scope.
* @returns {function()} Returns a de-registration function for all listeners.
*/
Expand Down