doc: add some API doc

Closes #4060

modules/angular2/src/core/di/binding.ts

@@ -266,14 +266,38 @@ export class ResolvedFactory {
 /**
  * Provides an API for imperatively constructing {@link Binding}s.
  *
- * This is only relevant for JavaScript. See {@link BindingBuilder}.
+ * To construct a {@link Binding}, bind a `token` to either a class, a value or a factory function.
+ * See {@link BindingBuilder} for more details.
+ *
+ * The `token` is most commonly an {@link angular2/di/OpaqueToken} or a class.
+ *
+ * `bind` is only relevant for JavaScript. For Dart use the {@link Binding} constructor.
  *
  * ## Example
  *
- * ```javascript
- * bind(MyInterface).toClass(MyClass)
+ * ```typescript
+ * // inj.get(MyClass) would instantiate MyClass
+ * bind(MyClass).toClass(MyClass);
  *
+ * // inj.get(MyClass) === 'my class'
+ * bind(MyClass).toValue('my class');
+ *
+ * // inj.get(MyClass) would instantiate the depenency and call the factory function with the
+ * // instance
+ * bind(MyClass).toFactory(dep => new MyClass(dep), [DepClass]);
+ *
+ * // inj.get(MyOtherClass) === inj.get(MyClass)
+ * bind(MyOtherClass).toAlias(MyClass);
  * ```
+ *
+ * ```dart
+ * var binding = new Binding(MyClass, toClass: MyClass);
+ * var binding = new Binding(MyClass, toValue: 'my class');
+ * var binding = new Binding(MyClass, toFactory: (dep) => new MyClass(dep),
+ *                           dependencies: [DepClass]);
+ *  var binding = new Binding(MyOtherClass, toAlias: MyClass);
+ * ```
+ *
  */
 export function bind(token): BindingBuilder {
   return new BindingBuilder(token);

modules/angular2/src/core/di/injector.ts

@@ -27,9 +27,21 @@ const _MAX_CONSTRUCTION_COUNTER = 10;
 
 export const UNDEFINED: Object = CONST_EXPR(new Object());
 
+/**
+ * Visibility of a {@link Binding}.
+ */
 export enum Visibility {
+  /**
+   * A `Public` {@link Binding} is only visible to regular (as opposed to host) child injectors.
+   */
   Public,
+  /**
+   * A `Private` {@link Binding} is only visible to host (as opposed to regular) child injectors.
+   */
   Private,
+  /**
+   * A `PublicAndPrivate` {@link Binding} is visible to both host and regular child injectors.
+   */
   PublicAndPrivate
 }
 

modules/angular2/src/core/di/opaque_token.ts

@@ -1,10 +1,27 @@
 import {CONST} from 'angular2/src/core/facade/lang';
 
+/**
+ * By binding to an `OpaqueToken` you can enable an application to return more meaningful error
+ * messages.
+ *
+ * ## Example
+ *
+ * ```
+ * // While the following would work, see below for the preferred way
+ * var binding = bind('value0').toValue(0);
+ * ...
+ * var value = injector.get('value0');
+ *
+ * // An OpaqueToken is the preferred way and lead to more helpful error messages
+ * export value0Token = new OpaqueToken('value0');
+ * var binding = bind(value0Token).toValue(0);
+ * ...
+ * var value = injector.get(value0Token);
+ * ```
+ */
 @CONST()
 export class OpaqueToken {
-  _desc: string;
+  constructor(private _desc: string) {}
 
-  constructor(desc: string) { this._desc = 'Token(' + desc + ')'; }
-
-  toString(): string { return this._desc; }
+  toString(): string { return `Token ${this._desc}`; }
 }