chore(docs): Basic descriptions for package libraries

lib/angular.dart

@@ -1,10 +1,31 @@
 /**
- * Angular is a framework for building single page web applications.
+ * Core functionality for angular.dart, a web framework for Dart.
+ *
+ *
+ * You must import the angular library to use it with Dart, like so:
+ *
+ *      import 'package:angular/angular.dart';
+ *
+ * The angular.dart library includes Angular's Directive and Filter classes:
+ *
+ *  - [angular.directive](#angular/angular-directive) lists all the basic directives
+ *  - [angular.filter] (#angular/angular-filter) lists all the basic filters
+ *
+ * You might also want to optionally import the following Angular libraries:
+ *
+ *   - [angular.animate](#angular/angular-animate) supports CSS animations that modify the
+ *   lifecycle of a DOM
+ *   element
+ *   - [angular.mock](#angular/angular-mock) provides classes and utilities for testing and
+ *   prototyping
+ *   - [angular.perf](#angular/angular-perf) provides classes to help evaluate performance in your
+ *   app
+ *
  *
  * Further reading:
  *
- *   - AngularJS [Overview](http://www.angularjs.org)
- *   - [Tutorial](https://github.com/angular/angular.dart.tutorial/wiki)
+ *   - AngularDart [Overview](http://www.angulardart.org)
+ *   - [Tutorial](https://angulardart.org/tutorial/)
  *   - [Mailing List](http://groups.google.com/d/forum/angular-dart?hl=en)
  *
  */

lib/animate/module.dart

@@ -1,16 +1,16 @@
 /**
- * Css animation and dom lifecycle management for Angular.
+ * CSS animation and DOM lifecycle management for AngularDart apps.
  *
- * The [animate] library makes it easier to build animations that affect the
- * lifecycle of dom elements. A useful example of this is animating the
- * removal of an element from the dom. In order to do this ideally the
+ * The [angular.animate](#angular/angular-animate) library makes it easier to build animations
+ * that affect the lifecycle of DOM elements. A useful example of this is animating the
+ * removal of an element from the DOM. In order to do this ideally the
  * operation should immediatly execute and manipulate the data model,
- * and the framework should handle the actual remove of the dom element once
+ * and the framework should handle the actual remove of the DOM element once
  * the animation complets. This ensures that the logic and model of the
  * application is seperated so that the state of the model can be reasoned
  * about without having to wory about future modifications of the model.
  * This library uses computed css styles to calculate the total duration
- * of an animation and handles the addition, removal, and modification of dom
+ * of an animation and handles the addition, removal, and modification of DOM
  * elements for block level directives such as `ng-if`, `ng-repeat`,
  * `ng-hide`, and more.
  *
@@ -19,30 +19,30 @@
  *     var module = new Module()
  *       ..install(new NgAnimateModule());
  *
- * Once the module has been installed, all block level dom manipulations will
+ * Once the module has been installed, all block level DOM manipulations will
  * be routed through the [CssAnimate] class instead of the
  * default [NgAnimate] implementation. This will, in turn,
  * perform the tracking, manipulation, and computation for animations.
  *
  * As an example of how this works, lets walk through what happens whan an
- * element is added to the dom. The [CssAnimate] implementation will add the
- * `.ng-enter` class to new dom elements when they are inserted into the dom
+ * element is added to the DOM. The [CssAnimate] implementation will add the
+ * `.ng-enter` class to new DOM elements when they are inserted into the DOM
  * by a directive and will read the computed style. If there is a
  * transition or keyframe animation, that animation duration will be read,
  * and the animation will be performed. The `.ng-enter-active` class will be
- * added to the dom element to set the target state for transition based
+ * added to the DOM element to set the target state for transition based
  * animations. When the animation is complete (determined by the
  * precomputed duration) the `.ng-enter` and `.ng-enter-active` classes
- * will be removed from the dom element.
+ * will be removed from the DOM element.
  *
- * When removing elements from the dom, a simliar pattern is followed. The
+ * When removing elements from the DOM, a simliar pattern is followed. The
  * `.ng-leave` class will be added to an element, the transition and / or
  * keyframe animation duration will be computed, and if it is non-zero the
  * animation will be run by adding the `.ng-leave-active` class. When
  * the animation completes, the element will be physically removed from the
- * dom.
+ * DOM.
  *
- * The same set of steps is run for each of the following types of dom
+ * The same set of steps is run for each of the following types of DOM
  * manipulation:
  *
  * * `.ng-enter`
@@ -75,7 +75,7 @@
  * `ctrl.visible` property goes from `true` to `false`.
  *
  * The [CssAnimate] will also do optimizations on running animations by
- * preventing child dom animations with the [AnimationOptimizer]. This
+ * preventing child DOM animations with the [AnimationOptimizer]. This
  * prevents transitions on child elements while the parent is animating,
  * but will not stop running transitions once they have started.
  *
@@ -88,9 +88,9 @@
  * running animation check.
  *
  * `ng-animate-children` allows animation to be controlled on large chunks of
- * dom. It only affects child elements, and allows the `always`, `never`,
+ * DOM. It only affects child elements, and allows the `always`, `never`,
  * and `auto` values to be specified. Always will always attempt animations
- * on child dom directives, never will always prevent them (except in the
+ * on child DOM directives, never will always prevent them (except in the
  * case where a given element has `ng-animate="always"` specified),
  * and `auto` will defer the decision to the currently running animation
  * check.

lib/bootstrap.dart

@@ -23,86 +23,92 @@ class AngularModule extends Module {
 
     type(MetadataExtractor);
     value(Expando, _elementExpando);
-    value(NgApp, new NgApp(dom.window.document.documentElement));
   }
 }
 
-Injector _defaultInjectorFactory(List<Module> modules) =>
-    new DynamicInjector(modules: modules);
-
 /**
- * This method is the main entry point to an angular application.
+ * Bootstraps AngularDart and defines which application module(s) are available to the app.
  *
- * # The [ngBootstrap] is responsible for:
+ * NgApp is how you configure and run an Angular application. NgApp is abstract. There are two
+ * implementations: one is dynamic, using Mirrors; the other is static, using code generation.
  *
- *   1. Locating the root element of the application,
- *   2. Creating Angular [NgZone]
- *   3. Inside the [NgZone] create an injector
- *   4. Retrieve the [Compiler] and compile the root eleement
+ * To create an NgApp, import angular_dynamic.dart and call ngDynamicApp like so:
+ *
+ *     import 'package:angular/angular.dart';
+ *     import 'package:angular/angular_dynamic.dart';
  *
+ *     class HelloWorldController {
+ *       ...
+ *       }
  *
- * # Parameters:
+ *     main() {
+ *      ngDynamicApp()
+ *        .addModule(new Module()..type(HelloWorldController))
+ *        .run();
+ *     }
  *
- *   - [module] Optional application module to add to the [Injector].
- *   - [modules] Optional list of [Module]s to add to the [Injector] (when more
- *     than one is needed).
- *   - [element] Optional root element of the application. If non specified, the
- *     the root element is looked up using the [selector]. If the selector can
- *     not identify a root, the root [HTML] element is used.
- *   - [selector] Optional CSS selector used to locate the root element for the
- *     application.
- *   - [injectorFactory] Optional factory responsible for creating the injector.
+ * On `pub build`, ngDynamicApp becomes ngStaticApp, as pub generates the getters,
+ * setters, annotations, and factories for the root Injector that [ngApp] creates. This
  *
  *
+ * Here, the ngBootstrap method performs the following actions:
+ *
+ *   1. Locating the root element of the application,
+ *   2. Creating Angular [NgZone]
+ *   3. Inside the [NgZone] create an injector
+ *   4. Retrieve the [Compiler] and compile the root element
  *
- * # A typical way to boostrap an Angular application:
  *
- *     var myAppModule = new Module();
- *     myAppModule.type(MyType);
- *     ....
- *     Injector injector = ngBootstrap(module: myAppModule);
  */
-Injector ngBootstrap({
-    Module module: null,
-    List<Module> modules: null,
-    dom.Element element: null,
-    String selector: '[ng-app]',
-    Injector injectorFactory(List<Module> modules): _defaultInjectorFactory}) {
-  _publishToJavaScript();
 
-  var ngModules = [new AngularModule()];
-  if (module != null) ngModules.add(module);
-  if (modules != null) ngModules.addAll(modules);
-  if (element == null) {
-    element = dom.querySelector(selector);
-    if (element == null) {
-      element = dom.window.document.childNodes
-          .firstWhere((e) => e is dom.Element);
-    }
+abstract class NgApp {
+  static _find(String selector, [dom.Element defaultElement]) {
+    var element = dom.window.document.querySelector(selector);
+    if (element == null) element = defaultElement;
+    if (element == null)throw "Could not find application element '$selector'.";
+    return element;
   }
 
-  // The injector must be created inside the zone, so we create the
-  // zone manually and give it back to the injector as a value.
-  NgZone zone = new NgZone();
-  ngModules.add(new Module()
+  final NgZone zone = new NgZone();
+  final AngularModule ngModule = new AngularModule();
+  final List<Module> modules = <Module>[];
+  dom.Element element;
+
+  dom.Element selector(String selector) => element = _find(selector);
+
+  NgApp(): element = _find('[ng-app]', dom.window.document.documentElement) {
+    modules.add(ngModule);
+    ngModule
       ..value(NgZone, zone)
-      ..value(NgApp, new NgApp(element))
-      ..factory(dom.Node, (i) => i.get(NgApp).root));
+      ..value(NgApp, this)
+      ..factory(dom.Node, (i) => i.get(NgApp).element);
+  }
+
+  Injector injector;
 
-  return zone.run(() {
-    var rootElements = [element];
-    Injector injector = injectorFactory(ngModules);
-    initializeDateFormatting(null, null).then((_) {
-      var compiler = injector.get(Compiler);
-      var blockFactory = compiler(rootElements, injector.get(DirectiveMap));
-      blockFactory(injector, rootElements);
+  NgApp addModule(Module module) {
+    modules.add(module);
+    return this;
+  }
+
+  Injector run() {
+    _publishToJavaScript();
+    return zone.run(() {
+      var rootElements = [element];
+      Injector injector = createInjector();
+      ExceptionHandler exceptionHandler = injector.get(ExceptionHandler);
+      initializeDateFormatting(null, null).then((_) {
+        try {
+          var compiler = injector.get(Compiler);
+          var blockFactory = compiler(rootElements, injector.get(DirectiveMap));
+          blockFactory(injector, rootElements);
+        } catch (e, s) {
+          exceptionHandler(e, s);
+        }
+      });
+      return injector;
     });
-    return injector;
-  });
-}
+  }
 
-/// Holds a reference to the root of the application used by ngBootstrap.
-class NgApp {
-  final dom.Element root;
-  NgApp(this.root);
+  Injector createInjector();
 }

lib/directive/module.dart

@@ -1,3 +1,12 @@
+/**
+*
+* Directives available in the main [angular.dart](#angular/angular) library.
+*
+* This package is imported for you as part of [angular.dart](#angular/angular),
+* and lists all of the basic directives that are part of Angular.
+*
+*
+*/
 library angular.directive;
 
 import 'package:di/di.dart';

lib/filter/module.dart

@@ -1,3 +1,12 @@
+/**
+*
+* Filters available in the main [angular.dart](#angular/angular) library.
+*
+* This package is imported for you as part of [angular.dart](#angular/angular),
+* and lists all of the basic filters that are part of Angular.
+*
+*
+*/
 library angular.filter;
 
 import 'dart:convert' show JSON;

lib/mock/module.dart

@@ -1,3 +1,16 @@
+/**
+*
+* Classes and utilities for testing and prototyping in AngularDart.
+*
+* This is an optional library. You must import it in addition to the [angular.dart]
+* (#angular/angular) library,
+* like so:
+*
+*      import 'package:angular/angular.dart';
+*      import 'package:angular/mock/module.dart';
+*
+*
+*/
 library angular.mock;
 
 import 'dart:async' as dart_async;

lib/perf/module.dart

@@ -1,3 +1,16 @@
+/**
+*
+* Classes and utilities for analyzing performance in AngularDart.
+*
+* This is an optional library. You must import it in addition to the [angular.dart]
+* (#angular/angular) library,
+* like so:
+*
+*      import 'package:angular/angular.dart';
+*      import 'package:angular/perf/module.dart';
+*
+*
+*/
 library angular.perf;
 
 import 'dart:html' as dom;

scripts/generate-documentation.sh

@@ -20,7 +20,6 @@ echo "Generating documentation"
     filter/module.dart \
     directive/module.dart \
     animate/module.dart \
-    utils.dart \
     mock/module.dart \
     perf/module.dart \