misc(docs): Edits and additions for Forms and Change Detection

modules/angular2/change_detection.js

@@ -2,7 +2,7 @@
  * @module
  * @public
  * @description
- * Description of the change_detection module
+ * Change detection enables data binding in Angular.
  */
 
 export {
@@ -79,5 +79,16 @@ export class JitChangeDetection extends ChangeDetection {
 
 var _registry = new PipeRegistry(defaultPipes);
 
+/**
+ * Implements dynamic change detection. See: [ChangeDetection] for more details.
+ *
+ * @exportedAs angular2/change_detection
+ */
 export var dynamicChangeDetection = new DynamicChangeDetection(_registry);
+
+/**
+ * Implements just-in-time change detection. See: [ChangeDetection] for more details.
+ *
+ * @exportedAs angular2/change_detection
+ */
 export var jitChangeDetection = new JitChangeDetection(_registry);

modules/angular2/forms.js

@@ -2,10 +2,12 @@
  * @module
  * @public
  * @description
- * This module is used for handling complex input, by defining and building a [FormObject] that consists of [Control]
+ * This module is used for handling user input, by defining and building a [FormObject] that consists of [Control]
  * objects, and mapping them onto the DOM. [Control] objects can then be used to read information from the form DOM
  * elements.
  *
+ * This module is not included in the `angular2` module; you must import the forms module explicitly.
+ *
  */
 
 export * from './src/forms/model';

modules/angular2/src/change_detection/interfaces.js

@@ -9,6 +9,29 @@ export class ProtoChangeDetector  {
   }
 }
 
+/**
+ * Interface used by Angular to control the change detection strategy for an application.
+ *
+ * Angular implements the following change detection strategies by default:
+ *
+ * - [dynamicChangeDetection]: slower, but does not require `eval()`.
+ * - [jitChangeDetection]: faster, but requires `eval()`.
+ *
+ * In JavaScript, you should always use `jitChangeDetection`, unless you are in an environment that has
+ * [CSP](https://developer.mozilla.org/en-US/docs/Web/Security/CSP), such as a Chrome Extension.
+ *
+ * In Dart, use `dynamicChangeDetection` during development. The Angular transformer generates an analog to the
+ * `jitChangeDetection` strategy at compile time.
+ *
+ *
+ * See: [dynamicChangeDetection], [jitChangeDetection]
+ *
+ * # Example
+ * ```javascript
+ * bootstrap(MyApp, [bind(ChangeDetection).toValue(dynamicChangeDetection)]);
+ * ```
+ * @exportedAs angular2/change_detection
+ */
 export class ChangeDetection {
   createProtoChangeDetector(name:string, changeControlStrategy:string=DEFAULT):ProtoChangeDetector{
     return null;

modules/angular2/src/core/exception_handler.js

@@ -3,6 +3,32 @@ import {isPresent, print} from 'angular2/src/facade/lang';
 import {ListWrapper, isListLikeIterable} from 'angular2/src/facade/collection';
 
 /**
+ * Provides a hook for centralized exception handling.
+ *
+ * The default implementation of `ExceptionHandler` prints error messages to the `Console`. To intercept error handling,
+ * write a custom exception handler that replaces this default as appropriate for your app.
+ *
+ * # Example
+ *
+ * ```javascript
+ * @Component({
+ *   selector: 'my-app',
+ *   injectables: [
+ *     bind(ExceptionHandler).toClass(MyExceptionHandler)
+ *   ]
+ * })
+ * @View(...)
+ * class MyApp { ... }
+ *
+ *
+ * class MyExceptionHandler implements ExceptionHandler {
+ *   call(error, stackTrace = null, reason = null) {
+ *     // do something with the exception
+ *   }
+ * }
+ *
+ * ```
+ *
  * @exportedAs angular2/core
  */
 @Injectable()

modules/angular2/src/render/dom/compiler/template_loader.js

@@ -11,7 +11,7 @@ import {UrlResolver} from 'angular2/src/services/url_resolver';
 
 /**
  * Strategy to load component templates.
- * @exportedAs angular2/core
+ * TODO: Make public API once we are more confident in this approach.
  */
 @Injectable()
 export class TemplateLoader {