docs(debugInfo): add docs for $compileProvider.debugInfoEnabled()

btford · vojtajina · commit c6bde520067e · 2014-08-27T20:45:59.000-07:00
diff --git a/docs/content/guide/index.ngdoc b/docs/content/guide/index.ngdoc
@@ -81,6 +81,7 @@ This is a short list of libraries with specific support and documentation for wo
 
 ### General
 
+* **Docs Page:** {@link guide/production Running an AngularJS App in Production}
 * **Javascript minification: **[Background](http://thegreenpizza.github.io/2013/05/25/building-minification-safe-angular.js-applications/), [ng-annotate automation tool](https://github.com/olov/ng-annotate)
 * **Analytics and Logging:** [Angularyitcs (Google Analytics)](http://ngmodules.org/modules/angularytics), [Angulartics (Analytics)](https://github.com/luisfarzati/angulartics), [Logging Client-Side Errors](http://www.bennadel.com/blog/2542-Logging-Client-Side-Errors-With-AngularJS-And-Stacktrace-js.htm)
 * **SEO:** [By hand](http://www.yearofmoo.com/2012/11/angularjs-and-seo.html), [prerender.io](http://prerender.io/), [Brombone](http://www.brombone.com/), [SEO.js](http://getseojs.com/), [SEO4Ajax](http://www.seo4ajax.com/)
diff --git a/docs/content/guide/production.ngdoc b/docs/content/guide/production.ngdoc
@@ -0,0 +1,42 @@
+@ngdoc overview
+@name  Running in Production
+@description
+
+# Running an AngularJS App in Production
+
+There are a few things you might consider when running your AngularJS application in production.
+
+
+## Disabling Debug Data
+
+By default AngularJS attaches information about scopes to DOM nodes, and adds CSS classes
+to data-bound elements. The information that is not included is:
+
+As a result of `ngBind`, `ngBindHtml` or `{{...}}` interpolations, binding data and CSS class
+`ng-class` is attached to the corresponding element.
+
+Where the compiler has created a new scope, the scope and either `ng-scope` or `ng-isolated-scope`
+CSS class are attached to the corresponding element. These scope references can then be accessed via
+`element.scope()` and `element.isolateScope()`.
+
+Tools like [Protractor](github.com/angular/protractor) and
+[Batarang](https://github.com/angular/angularjs-batarang) need this information to run,
+but you can disable this in production for a significant performance boost with:
+
+```js
+myApp.config(['$compileProvider', function ($compileProvider) {
+  $compileProvider.debugInfoEnabled(false);
+}]);
+```
+
+If you wish to debug an application with this information then you should open up a debug
+console in the browser then call this method directly in this console:
+
+```js
+angular.reloadWithDebugInfo();
+```
+
+The page should reload and the debug information should now be available.
+
+For more see the docs pages on {@link ng.$compileProvider#debugInfoEnabled `$compileProvider`}
+and {@link ng/function/angular.reloadWithDebugInfo `angular.reloadWithDebugInfo`}.
diff --git a/src/Angular.js b/src/Angular.js
@@ -1450,20 +1450,9 @@ function bootstrap(element, modules, config) {
  * @module ng
  * @description
  * Use this function to reload the current application with debug information turned on.
+ * This takes precedence over a call to `$compileProvider.debugInfoEnabled(false)`.
  *
- * To improve performance adding various debugging information can be disabled.
- * See {@link $compileProvider#debugInfoEnabled}.
- *
- * This overrides any setting of `$compileProvider.debugInfoEnabled()` that you defined in your
- * modules. If you wish to debug an application via this information then you should open up a debug
- * console in the browser then call this method directly in this console:
- *
- * ```js
- * angular.reloadWithDebugInfo();
- * ```
- *
- * The page should reload and the debug information should now be available.
- *
+ * See {@link ng.$compileProvider#debugInfoEnabled} for more.
  */
 function reloadWithDebugInfo() {
   window.name = 'NG_ENABLE_DEBUG_INFO!' + window.name;
diff --git a/src/ng/compile.js b/src/ng/compile.js
@@ -685,6 +685,9 @@ function $CompileProvider($provide, $$sanitizeUriProvider) {
    * * `ng-binding` CSS class
    * * `$binding` data property containing an array of the binding expressions
    *
+   * You may want to use this in production for a significant performance boost. See
+   * {@link guide/production#disabling-debug-data Disabling Debug Data} for more.
+   *
    * The default value is true.
    */
   var debugInfoEnabled = true;
