chore(docs): more detail for app:dynamic in 0.9.11

Author: naomiblack

example/web/animation.dart

@@ -17,14 +17,18 @@ class AnimationDemoController {
   var currentPage = "About";
 }
 
+class AnimationDemoModule extends Module {
+  AnimationDemoModule() {
+    install(new NgAnimateModule());
+    type(RepeatDemoComponent);
+    type(VisibilityDemoComponent);
+    type(StressDemoComponent);
+    type(CssDemoComponent);
+    type(AnimationDemoController);
+  }
+}
 main() {
   dynamicApplication()
-      .addModule(new Module()
-          ..type(RepeatDemoComponent)
-          ..type(VisibilityDemoComponent)
-          ..type(StressDemoComponent)
-          ..type(CssDemoComponent)
-          ..type(AnimationDemoController))
-      .addModule(new NgAnimateModule())
+      .addModule(new AnimationDemoModule())
       .run();
 }

lib/angular_dynamic.dart

@@ -2,6 +2,10 @@
  * Bootstrapping for Angular applications via [dart:mirrors](https://api.dartlang
  * .org/apidocs/channels/stable/dartdoc-viewer/dart-mirrors) for development.
  *
+ * Angular apps that use  [dynamicApplication](#angular-app-dynamic@id_dynamicApplication) rely on
+ * dynamic transformation at compile time to generate the getters, setters, annotations, and
+ * factories needed for tree shaking during compilation with `dart2js`. See the [angular:app]
+ * (#angular-app) library for a discussion of how this works.
  */
 library angular.app.dynamic;
 

lib/angular_static.dart

@@ -1,6 +1,33 @@
 /**
  * Bootstrapping for Angular applications via code generation, for production.
  *
+ * Most angular.dart apps rely on dynamic transformation at compile time to generate the artifacts
+ * needed for tree shaking during compilation with `dart2js`. However,
+ * if your deployment environment makes it impossible for you to use transformers,
+ * you can call [staticApplication](#angular-app-static@id_staticApplication)
+ * directly in your `main()` function, and explicitly define the getters, setters, annotations, and
+ * factories yourself.
+ *
+ *     import 'package:angular/angular.dart';
+ *     import 'package:angular/angular_static.dart';
+ *
+ *     class MyModule extends Module {
+ *       MyModule() {
+ *         type(HelloWorldController);
+ *       }
+ *     }
+ *
+ *     main() {
+ *       staticApplication()
+ *           .addModule(new MyModule())
+ *           .run();
+ *     }
+ *
+ *  Note that you must explicitly import both
+ * `angular.dart` and `angular_static.dart` at the start of your file. See [staticApplication]
+ * (#angular-app-static@id_staticApplication) for more on explicit definitions required with this
+ * library.
+ *
  */
 library angular.app.static;
 

lib/bootstrap.dart

@@ -1,8 +1,66 @@
 /**
  * Bootstrapping for Angular applications via [app:dynamic](#angular-app-dynamic) for development,
- * or
- * [app:static](#angular-app-static) for production.
+ * or [app:static](#angular-app-static) for production.
  *
+ * In your `main()` function, you bootstrap Angular by explicitly defining and adding a module for
+ * your app:
+ *
+ *     import 'package:angular/angular.dart';
+ *     import 'package:angular/angular_dynamic.dart';
+ *
+ *     class MyModule extends Module {
+ *       MyModule() {
+ *         type(HelloWorldController);
+ *       }
+ *     }
+ *
+ *     main() {
+ *       dynamicApplication()
+ *           .addModule(new MyModule())
+ *           .run();
+ *     }
+ *
+ * In the code above, we use [dynamicApplication](#angular-app-dynamic) to
+ * take advantage of [dart:mirrors]
+ * (https://api.dartlang.org/apidocs/channels/stable/dartdoc-viewer/dart-mirrors) during
+ * development. When you run the app in Dartium, you are using the implementation found under
+ * [app:dynamic](#angular-app-dynamic). Note also that you must explicitly import both
+ * `angular.dart` and `angular_dynamic.dart` at the start of your file.
+ *
+ * For production, transformers defined in your `pubspec.yaml` file convert the compiled code to
+ * use the [app:static](#angular-app-static) implementation when you run `pub build`. Instead of
+ * relying on mirrors, this automatically generates the getters, setters, annotations, and factories
+ * needed by Dart for tree shaking in dart2js, ensuring that your final JavaScript code contains
+ * only what is used by the root Injector that ngApp creates.
+ *
+ * Add the transformers rule shown below to your `pubspec.yaml`:
+ *
+ *     name: angular_dart_example
+ *     version: 0.0.1
+ *     dependencies:
+ *       angular: '>= 0.9.11'
+ *       browser: any
+ *       unittest: any
+ *
+ *     transformers:
+ *     - angular
+ *
+ * If your app structure makes use of directories for storing your templates,
+ * you must also specify rules for `html_files` to ensure that the transformers pick up those
+ * files. You only need to specify the HTML files; the parser will infer the correct `.dart` and
+ * CSS files to include.
+ *
+ * For example:
+ *
+ *     transformers:
+ *     - angular:
+ *         html_files:
+ *         - lib/_somelibrary/_some_component.html
+ *
+ * If you need a way to build your app without transformers, you can use
+ * [staticApplication](#angular-app-static@id_staticApplication) directly, instead of
+ * [dynamicApplication](#angular-app-dynamic@id_dynamicApplication). See the documentation for
+ * the [app:static](#angular-app-static) library definition for more on this use case.
  */
 library angular.app;
 
@@ -21,17 +79,15 @@ import 'package:angular/routing/module.dart';
 import 'package:angular/introspection_js.dart';
 
 /**
- * This is the top level module which describes the core angular of angular including filters and
- * directives. The module is automatically included with [Application]
+ * This is the top level module which describes all Angular components,
+ * including services, filters and directives. When writing an Angular application,
+ * AngularModule is automatically included.
  *
- * The Module is made up of
+ * You can use AngularModule explicitly when creating a custom Injector that needs to know
+ * about Angular services, filters, and directives. When writing tests, this is typically done for
+ * you by the [SetUpInjector](#angular-mock@id_setUpInjector) method.
  *
- * - [NgCoreModule]
- * - [NgCoreDomModule]
- * - [NgDirectiveModule]
- * - [NgFilterModule]
- * - [NgPerfModule]
- * - [NgRoutingModule]
+
  */
 class AngularModule extends Module {
   AngularModule() {
@@ -48,27 +104,14 @@ class AngularModule extends Module {
 }
 
 /**
- * Application is how you configure and run an Angular application. Application is abstract. There are two
- * implementations: one is dynamic, using Mirrors; the other is static, using code generation.
- *
- * To create an Application, import angular_dynamic.dart and call dynamicApplication like so:
- *
- *     import 'package:angular/angular.dart';
- *     import 'package:angular/angular_dynamic.dart';
- *
- *     class HelloWorldController {
- *       ...
- *       }
- *
- *     main() {
- *      dynamicApplication()
- *        .addModule(new Module()..type(HelloWorldController))
- *        .run();
- *     }
- *
- * On `pub build`, dynamicApplication becomes staticApplication, as pub generates the getters,
- * setters, annotations, and factories for the root Injector that [ngApp] creates. This
+ * Application is how you configure and run an Angular application. There are two
+ * implementations for this abstract class:
  *
+ * - [app:dynamic](#angular-app-dynamic) for development, which uses transformers to generate the
+ * getters, setters, annotations, and factories needed by [dart:mirrors](https://api.dartlang.org/apidocs/channels/stable/dartdoc-viewer/dart-mirrors) for tree shaking
+ * - [app:static](#angular-app-static), for apps that explicitly specify their own getters,
+ * setters, annotations, and factories and do not rely on transformation or  [dart:mirrors]
+ * (https://api.dartlang.org/apidocs/channels/stable/dartdoc-viewer/dart-mirrors)
  *
  */