docs($rootScope): better document infinite digest and ttl

2 files changed, 11 insertions, 4 deletions

diff --git a/docs/content/error/rootScope/infdig.ngdoc b/docs/content/error/rootScope/infdig.ngdoc
index cffe4de2..137bc120 100644
--- a/docs/content/error/rootScope/infdig.ngdoc
+++ b/docs/content/error/rootScope/infdig.ngdoc
@@ -3,7 +3,8 @@
 @fullName Infinite $digest Loop
 @description
 
-This error occurs when the application's model becomes unstable and each `$digest` cycle triggers a state change and subsequent `$digest` cycle. Angular detects this situation and prevents an infinite loop from causing the browser to become unresponsive.
+This error occurs when the application's model becomes unstable and each `$digest` cycle triggers a state change and subsequent `$digest` cycle.
+Angular detects this situation and prevents an infinite loop from causing the browser to become unresponsive.
 
 For example, the situation can occur by setting up a watch on a path and subsequently updating the same path when the value changes.
 
@@ -11,4 +12,6 @@ For example, the situation can occur by setting up a watch on a path and subsequ
 $scope.$watch('foo', function() {
   $scope.foo = $scope.foo + 1;
 });
-```
\ No newline at end of file
+```
+
+The maximum number of allowed iterations of the `$digest` cycle is controlled via TTL setting which can be configured via {@link api/ng.$rootScopeProvider $rootScopeProvider}.
diff --git a/src/ng/rootScope.js b/src/ng/rootScope.js
index 48f8a07b..aa3a6f13 100644
--- a/src/ng/rootScope.js
+++ b/src/ng/rootScope.js
@@ -40,11 +40,15 @@
  * @methodOf ng.$rootScopeProvider
  * @description
  *
- * Sets the number of digest iterations the scope should attempt to execute before giving up and
- * assuming that the model is unstable.
+ * Sets the number of `$digest` iterations the scope should attempt to execute before giving up and assuming that the model is unstable.
  *
  * The current default is 10 iterations.
  *
+ * In complex applications it's possible that the dependencies between `$watch`s will result in several digest iterations.
+ * However if an application needs more than the default 10 digest iterations for its model to stabilize then you should investigate what is causing the model to continuously change during the digest.
+ *
+ * Increasing the TTL could have performance implications, so you should not change it without proper justification.
+ *
  * @param {number} limit The number of digest iterations.
  */