docs(Http): add docs for Http lib

Fixes #2442

modules/angular2/src/http/static_request.ts

@@ -4,26 +4,37 @@ import {IRequestOptions, Request as IRequest} from './interfaces';
 import {Headers} from './headers';
 import {BaseException, RegExpWrapper} from 'angular2/src/facade/lang';
 
-// TODO(jeffbcross): implement body accessors
+// TODO(jeffbcross): properly implement body accessors
+/**
+ * Creates `Request` instances with default values.
+ *
+ * The Request's interface is inspired by the Request constructor defined in the [Fetch
+ * Spec](https://fetch.spec.whatwg.org/#request-class),
+ * but is considered a static value whose body can be accessed many times. There are other
+ * differences in the implementation, but this is the most significant.
+ */
 export class Request implements IRequest {
+  /**
+   * Http method with which to perform the request.
+   *
+   * Defaults to GET.
+   */
   method: RequestMethods;
   mode: RequestModesOpts;
   credentials: RequestCredentialsOpts;
-  headers: Headers;
-  /*
-   * Non-Standard Properties
+  /**
+   * Headers object based on the `Headers` class in the [Fetch
+   * Spec](https://fetch.spec.whatwg.org/#headers-class). {@link Headers} class reference.
    */
-  // This property deviates from the standard. Body can be set in constructor, but is only
-  // accessible
-  // via json(), text(), arrayBuffer(), and blob() accessors, which also change the request's state
-  // to "used".
-  private body: URLSearchParams | FormData | Blob | string;
+  headers: Headers;
 
-  constructor(public url: string, {body, method = RequestMethods.GET, mode = RequestModesOpts.Cors,
-                                   credentials = RequestCredentialsOpts.Omit,
-                                   headers = new Headers()}: IRequestOptions = {}) {
-    this.body = body;
-    // Defaults to 'GET', consistent with browser
+  private _body: URLSearchParams | FormData | Blob | string;
+
+  constructor(/** Url of the remote resource */ public url: string,
+              {body, method = RequestMethods.GET, mode = RequestModesOpts.Cors,
+               credentials = RequestCredentialsOpts.Omit,
+               headers = new Headers()}: IRequestOptions = {}) {
+    this._body = body;
     this.method = method;
     // Defaults to 'cors', consistent with browser
     // TODO(jeffbcross): implement behavior
@@ -31,9 +42,13 @@ export class Request implements IRequest {
     // Defaults to 'omit', consistent with browser
     // TODO(jeffbcross): implement behavior
     this.credentials = credentials;
-    // Defaults to empty headers object, consistent with browser
     this.headers = headers;
   }
 
-  text(): String { return this.body ? this.body.toString() : ''; }
+  /**
+   * Returns the request's body as string, assuming that body exists. If body is undefined, return
+   * empty
+   * string.
+   */
+  text(): String { return this._body ? this._body.toString() : ''; }
 }