Reproducing changes from https://chromiumcodereview.appspot.com/23556009/

sdk/lib/html/dart2js/html_dart2js.dart

Index: sdk/lib/html/dart2js/html_dart2js.dart
diff --git a/sdk/lib/html/dart2js/html_dart2js.dart b/sdk/lib/html/dart2js/html_dart2js.dart
index 62b96f20078d70783931d555f0243167caf08d85..3a6983a5e16125f313b60a6aa4cf2c59b84a6c18 100644
--- a/sdk/lib/html/dart2js/html_dart2js.dart
+++ b/sdk/lib/html/dart2js/html_dart2js.dart
@@ -12601,37 +12601,58 @@ class HtmlOptionsCollection extends HtmlCollection native "HTMLOptionsCollection
 // BSD-style license that can be found in the LICENSE file.
 
 
-/**
- * A utility for retrieving data from a URL.
- *
- * HttpRequest can be used to obtain data from http, ftp, and file
- * protocols.
- *
- * For example, suppose we're developing these API docs, and we
- * wish to retrieve the HTML of the top-level page and print it out.
- * The easiest way to do that would be:
- *
- *     HttpRequest.getString('http://api.dartlang.org').then((response) {
- *       print(response);
- *     });
- *
- * **Important**: With the default behavior of this class, your
- * code making the request should be served from the same origin (domain name,
- * port, and application layer protocol) as the URL you are trying to access
- * with HttpRequest. However, there are ways to
- * [get around this restriction](http://www.dartlang.org/articles/json-web-service/#note-on-jsonp).
- *
- * See also:
- *
- * * [Dart article on using HttpRequests](http://www.dartlang.org/articles/json-web-service/#getting-data)
- * * [JS XMLHttpRequest](https://developer.mozilla.org/en-US/docs/DOM/XMLHttpRequest)
- * * [Using XMLHttpRequest](https://developer.mozilla.org/en-US/docs/DOM/XMLHttpRequest/Using_XMLHttpRequest)
+ /**
+  * A client-side XHR request for getting data from a URL,
+  * formally known as XMLHttpRequest.
+  *
+  * HttpRequest can be used to obtain data from HTTP and FTP protocols,
+  * and is useful for AJAX-style page updates.
+  *
+  * The simplest way to get the contents of a text file, such as a
+  * JSON-formatted file, is with [getString].
+  * For example, the following code gets the contents of a JSON file
+  * and prints its length:
+  *
+  *     var path = 'myData.json';
+  *     HttpRequest.getString(path)
+  *         .then((String fileContents) {
+  *           print(fileContents.length);
+  *         })
+  *         .catchError((Error error) {
+  *           print(error.toString());
+  *         });
+  *
+  * ## Fetching data from other servers
+  *
+  * For security reasons, browsers impose restrictions on requests
+  * made by embedded apps.
+  * With the default behavior of this class,
+  * the code making the request must be served from the same origin
+  * (domain name, port, and application layer protocol)
+  * as the requested resource.
+  * In the example above, the myData.json file must be co-located with the
+  * app that uses it.
+  * You might be able to
+  * [get around this restriction](http://www.dartlang.org/articles/json-web-service/#a-note-on-cors-and-httprequest)
+  * by using CORS headers or JSONP.
+  *
+  * ## Other resources
+  *
+  * * [Fetch Data Dynamically](https://www.dartlang.org/docs/tutorials/fetchdata/),
+  * a tutorial from _A Game of Darts_,
+  * shows two different ways to use HttpRequest to get a JSON file.
+  * * [Get Input from a Form](https://www.dartlang.org/docs/tutorials/forms/),
+  * another tutorial from _A Game of Darts_,
+  * shows using HttpRequest with a custom server.
+  * * [Dart article on using HttpRequests](http://www.dartlang.org/articles/json-web-service/#getting-data)
+  * * [JS XMLHttpRequest](https://developer.mozilla.org/en-US/docs/DOM/XMLHttpRequest)
+  * * [Using XMLHttpRequest](https://developer.mozilla.org/en-US/docs/DOM/XMLHttpRequest/Using_XMLHttpRequest)
  */
 @DomName('XMLHttpRequest')
 class HttpRequest extends HttpRequestEventTarget native "XMLHttpRequest" {
 
   /**
-   * Creates a URL get request for the specified [url].
+   * Creates a GET request for the specified [url].
    *
    * The server response must be a `text/` mime type for this request to
    * succeed.