docs(*): clarify limitations of app bootstrapping

Narretz · Narretz · commit b04871b43f81 · 2016-02-09T11:41:54.000+01:00
- Note that bootstrapping on elements with transclusion directives is dangerous and not recommended. - group info on limitations, and add them to the guide Closes #11421 Closes #13572 Closes #12583
diff --git a/docs/content/guide/bootstrap.ngdoc b/docs/content/guide/bootstrap.ngdoc
@@ -53,13 +53,13 @@ initialization.
 
 Angular initializes automatically upon `DOMContentLoaded` event or when the `angular.js` script is
 evaluated if at that time `document.readyState` is set to `'complete'`. At this point Angular looks
-for the {@link ng.directive:ngApp `ng-app`} directive which designates your application root.
-If the {@link ng.directive:ngApp `ng-app`} directive is found then Angular will:
+for the {@link ng.directive:ngApp `ngApp`} directive which designates your application root.
+If the {@link ng.directive:ngApp `ngApp`} directive is found then Angular will:
 
   * load the {@link guide/module module} associated with the directive.
   * create the application {@link auto.$injector injector}
   * compile the DOM treating the {@link ng.directive:ngApp
-    `ng-app`} directive as the root of the compilation. This allows you to tell it to treat only a
+    `ngApp`} directive as the root of the compilation. This allows you to tell it to treat only a
     portion of the DOM as an Angular application.
 
 
@@ -142,6 +142,17 @@ This is the sequence that your code should follow:
   2. Call {@link angular.bootstrap} to {@link compiler compile} the element into an
   executable, bi-directionally bound application.
 
+## Things to keep in mind
+
+There a few things to keep in mind regardless of automatic or manual bootstrapping:
+
+- While it's possible to bootstrap more than one AngularJS application per page, we don't actively
+  test against this scenario. It's possible that you'll run into problems, especially with complex apps, so
+  caution is advised.
+- Do not bootstrap your app on an element with a directive that uses {@link ng.$compile#transclusion transclusion}, such as
+  {@link ng.ngIf `ngIf`}, {@link ng.ngInclude `ngInclude`} and {@link ngRoute.ngView `ngView`}.
+  Doing this misplaces the app {@link ng.$rootElement `$rootElement`} and the app's {@link auto.$injector injector},
+  causing animations to stop working and making the injector inaccessible from outside the app.
 
 ## Deferred Bootstrap
 
diff --git a/src/Angular.js b/src/Angular.js
@@ -1402,10 +1402,17 @@ function getNgAttribute(element, ngAttr) {
  * designates the **root element** of the application and is typically placed near the root element
  * of the page - e.g. on the `<body>` or `<html>` tags.
  *
- * Only one AngularJS application can be auto-bootstrapped per HTML document. The first `ngApp`
- * found in the document will be used to define the root element to auto-bootstrap as an
- * application. To run multiple applications in an HTML document you must manually bootstrap them using
- * {@link angular.bootstrap} instead. AngularJS applications cannot be nested within each other.
+ * There are a few things to keep in mind when using `ngApp`:
+ * - only one AngularJS application can be auto-bootstrapped per HTML document. The first `ngApp`
+ *   found in the document will be used to define the root element to auto-bootstrap as an
+ *   application. To run multiple applications in an HTML document you must manually bootstrap them using
+ *   {@link angular.bootstrap} instead.
+ * - AngularJS applications cannot be nested within each other.
+ * - Do not use a directive that uses {@link ng.$compile#transclusion transclusion} on the same element as `ngApp`.
+ *   This includes directives such as {@link ng.ngIf `ngIf`}, {@link ng.ngInclude `ngInclude`} and
+ *   {@link ngRoute.ngView `ngView`}.
+ *   Doing this misplaces the app {@link ng.$rootElement `$rootElement`} and the app's {@link auto.$injector injector},
+ *   causing animations to stop working and making the injector inaccessible from outside the app.
  *
  * You can specify an **AngularJS module** to be used as the root module for the application.  This
  * module will be loaded into the {@link auto.$injector} when the application is bootstrapped. It
@@ -1545,16 +1552,25 @@ function angularInit(element, bootstrap) {
  * @description
  * Use this function to manually start up angular application.
  *
- * See: {@link guide/bootstrap Bootstrap}
- *
- * Note that Protractor based end-to-end tests cannot use this function to bootstrap manually.
- * They must use {@link ng.directive:ngApp ngApp}.
+ * For more information, see the {@link guide/bootstrap Bootstrap guide}.
  *
  * Angular will detect if it has been loaded into the browser more than once and only allow the
  * first loaded script to be bootstrapped and will report a warning to the browser console for
  * each of the subsequent scripts. This prevents strange results in applications, where otherwise
  * multiple instances of Angular try to work on the DOM.
  *
+ * <div class="alert alert-warning">
+ * **Note:** Protractor based end-to-end tests cannot use this function to bootstrap manually.
+ * They must use {@link ng.directive:ngApp ngApp}.
+ * </div>
+ *
+ * <div class="alert alert-warning">
+ * **Note:** Do not bootstrap the app on an element with a directive that uses {@link ng.$compile#transclusion transclusion},
+ * such as {@link ng.ngIf `ngIf`}, {@link ng.ngInclude `ngInclude`} and {@link ngRoute.ngView `ngView`}.
+ * Doing this misplaces the app {@link ng.$rootElement `$rootElement`} and the app's {@link auto.$injector injector},
+ * causing animations to stop working and making the injector inaccessible from outside the app.
+ * </div>
+ *
  * ```html
  * <!doctype html>
  * <html>
