docs: bootstrap method

mhevery · mhevery · commit 956b8c879266 · 2015-03-13T21:55:02.000Z
diff --git a/modules/angular2/src/core/annotations/annotations.js b/modules/angular2/src/core/annotations/annotations.js
@@ -1,6 +1,10 @@
 import {ABSTRACT, CONST, normalizeBlank, isPresent} from 'angular2/src/facade/lang';
 import {ListWrapper, List} from 'angular2/src/facade/collection';
 
+/**
+ * Directives allow you to attach behavior to the DOM elements. Directive is an abstract concept, instead use concrete
+ * directives such as: [Component], [Decorator] or [Viewport].
+ */
 @ABSTRACT()
 export class Directive {
   selector:any; //string;
diff --git a/modules/angular2/src/core/application.js b/modules/angular2/src/core/application.js
@@ -117,18 +117,113 @@ function _createVmZone(givenReporter:Function): VmTurnZone {
   return zone;
 }
 
-// Multiple calls to this method are allowed. Each application would only share
-// _rootInjector, which is not user-configurable by design, thus safe to share.
-export function bootstrap(appComponentType: Type, bindings: List<Binding>=null, givenBootstrapErrorReporter: Function=null): Promise {
+/**
+ * Bootstrapping for Angular applications. 
+ * 
+ * You instantiate an Angular application by explicitly specifying a component to use as the root component for your 
+ * application via the `bootstrap()` method.
+ * 
+ * ## Simple Example
+ * 
+ * Assuming this `index.html`:
+ *     <html>
+ *       <!-- load Angular script tags here. -->
+ *       <body>
+ *         <my-app>loading...</my-app>
+ *       </body>
+ *     </html>
+ * 
+ * An application is bootstrapped inside an existing browser DOM, typically `index.html`. Unlike Angular 1, Angular 2
+ * does not compile/process bindings in `index.html`. This is mainly for security reasons, as well as architectural
+ * changes in Angular 2. This means that `index.html` can safely be processed using server-side binding technologies,
+ * which may use double-curly `{{syntax}}` without collision from Angular 2 component double-curly `{{syntax}}`.
+ * 
+ * We can use this script code:
+ *     @Component({
+ *        selector: 'my-app'   
+ *     })
+ *     @Template({
+ *        inline: 'Hello {{name}}!'
+ *     })
+ *     class MyApp {
+ *       name:string;
+ * 
+ *       constructor() {
+ *         this.name = 'World';   
+ *       }
+ *     }
+ * 
+ *     main() {
+ *       bootstrap(MyApp);
+ *     }
+ * 
+ * When the app developer invokes `bootstrap()` with the root component `MyApp` as its argument, Angular performs the 
+ * following tasks:
+ * 
+ *  1. It uses the component's `selector` property to locate the DOM element which needs to be upgraded into 
+ *     the angular component.
+ *  2. It creates a new child injector (from the primordial injector) and configures the injector with the component's 
+ *     `services`. Optionally, you can also override the injector configuration for an app by invoking  
+ *     `bootstrap` with the `componentServiceBindings` argument.
+ *  3. It creates a new [Zone] and connects it to the angular application's change detection domain instance. 
+ *  4. It creates a shadow DOM on the selected component's host element and loads the template into it.
+ *  5. It instantiates the specified component.
+ *  6. Finally, Angular performs change detection to apply the initial data bindings for the application.
+ * 
+ * 
+ * ## Instantiating Multiple Applications on a Single Page
+ * 
+ * There are two ways to do this.
+ * 
+ * 
+ * ### Isolated Applications
+ * 
+ * Angular creates a new application each time that the `bootstrap()` method is invoked. When multiple applications 
+ * are created for a page, Angular treats each application as independent within an isolated change detection and 
+ * [Zone] domain. If you need to share data between applications, use the strategy described in the next 
+ * section, "Applications That Share Change Detection." 
+ *
+ * 
+ * ### Applications That Share Change Detection
+ * 
+ * If you need to bootstrap multiple applications that share common data, the applications must share a common 
+ * change detection and zone. To do that, create a meta-component that lists the application components in its template.
+ * By only  invoking the bootstrap()` method once with the meta-component as its argument, you ensure that only a single
+ * change detection zone is created and therefore data can be shared across the applications.
+ * 
+ * 
+ * ## Primordial Injector
+ * 
+ * When working within a browser window, there are many singleton resources: cookies, title, location, and others. 
+ * Angular services that represent these resources must likewise be shared across all Angular applications that 
+ * occupy the same browser window.  For this reason, Angular creates exactly one global primordial injector which stores
+ * all shared services, and each angular application injector has the primordial injector as its parent. 
+ * 
+ * Each application has its own private injector as well. When there are multiple applications on a page, Angular treats 
+ * each application injector's services as private to that application.
+ * 
+ * 
+ * # API
+ * - [appComponentType]: The root component which should act as the application. This is a reference to a [Type]
+ *   which is annotated with `@Component(...)`.
+ * - [componentServiceBindings]: An additional set of bindings that can be added to the [Component.services] to 
+ *   override default injection behavior.
+ * - [errorReporter]: `function(exception:any, stackTrace:string)` a default error reporter for unhandled exceptions.
+ * 
+ * Returns the application`s private [Injector].
+ */
+export function bootstrap(appComponentType: Type, 
+                          componentServiceBindings: List<Binding>=null, 
+                          errorReporter: Function=null): Promise<Injector> {
   BrowserDomAdapter.makeCurrent();
   var bootstrapProcess = PromiseWrapper.completer();
 
-  var zone = _createVmZone(givenBootstrapErrorReporter);
+  var zone = _createVmZone(errorReporter);
   zone.run(() => {
     // TODO(rado): prepopulate template cache, so applications with only
     // index.html and main.js are possible.
 
-    var appInjector = _createAppInjector(appComponentType, bindings, zone);
+    var appInjector = _createAppInjector(appComponentType, componentServiceBindings, zone);
 
     PromiseWrapper.then(appInjector.asyncGet(appViewToken),
       (rootView) => {
