docs: api docs for Renderer and all the related apis

Closes #4459

modules/angular2/src/core/linker/element_ref.ts

@@ -54,15 +54,16 @@ export class ElementRef implements RenderElementRef {
    * <div class="callout is-critical">
    *   <header>Use with caution</header>
    *   <p>
-   *    Use this api as the last resort when direct access to DOM is needed. Use templating and
-   *    data-binding provided by Angular instead.
+   *    Use this API as the last resort when direct access to DOM is needed. Use templating and
+   *    data-binding provided by Angular instead. Alternatively you take a look at {@link Renderer}
+   *    which provides API that can safely be used even when direct access to native elements is not
+   *    supported.
    *   </p>
    *   <p>
    *    Relying on direct DOM access creates tight coupling between your application and rendering
    *    layers which will make it impossible to separate the two and deploy your application into a
    *    web worker.
    *   </p>
-   *   <!-- TODO: add info about custom renderers that should be used instead -->
    * </div>
    */
   get nativeElement(): any { return this._renderer.getNativeElementSync(this); }

modules/angular2/src/core/metadata/view.ts

@@ -4,7 +4,7 @@ import {ViewEncapsulation} from 'angular2/src/core/render/api';
 export {ViewEncapsulation} from 'angular2/src/core/render/api';
 
 /**
- * Declares the available HTML templates for an application.
+ * Metadata properties available for configuring Views.
  *
  * Each Angular component requires a single `@Component` and at least one `@View` annotation. The
  * `@View` annotation specifies the HTML template to use, and lists the directives that are active
@@ -39,19 +39,23 @@ export class ViewMetadata {
   /**
    * Specifies a template URL for an Angular component.
    *
-   * NOTE: either `templateUrl` or `template` should be used, but not both.
+   * NOTE: Only one of `templateUrl` or `template` can be defined per View.
+   *
+   * <!-- TODO: what's the url relative to? -->
    */
   templateUrl: string;
 
   /**
    * Specifies an inline template for an Angular component.
    *
-   * NOTE: either `templateUrl` or `template` should be used, but not both.
+   * NOTE: Only one of `templateUrl` or `template` can be defined per View.
    */
   template: string;
 
   /**
    * Specifies stylesheet URLs for an Angular component.
+   *
+   * <!-- TODO: what's the url relative to? -->
    */
   styleUrls: string[];
 

modules/angular2/src/core/render/dom/dom_tokens.ts

@@ -1,10 +1,22 @@
 import {OpaqueToken, Binding} from 'angular2/src/core/di';
 import {CONST_EXPR, StringWrapper, Math} from 'angular2/src/core/facade/lang';
 
+/**
+ * A DI Token representing the main rendering context. In a browser this is the DOM Document.
+ *
+ * Note: Document might not be available in the Application Context when Application and Rendering
+ * Contexts are not the same (e.g. when running the application into a Web Worker).
+ */
 export const DOCUMENT: OpaqueToken = CONST_EXPR(new OpaqueToken('DocumentToken'));
 
 /**
- * A unique id (string) for an angular application.
+ * A DI Token representing a unique string id assigned to the application by Angular and used
+ * primarily for prefixing application attributes and CSS styles when
+ * {@link ViewEncapsulation#Emulated} is being used.
+ *
+ * If you need to avoid randomly generated value to be used as an application id, you can provide
+ * a custom value via a DI binding <!-- TODO: provider --> configuring the root {@link Injector}
+ * using this token.
  */
 export const APP_ID: OpaqueToken = CONST_EXPR(new OpaqueToken('AppId'));