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

tools/dom/templates/html/impl/impl_XMLHttpRequest.darttemplate

 // Copyright (c) 2012, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 part of $LIBRARYNAME;
 
-/**
- * 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)
  */
 $(ANNOTATIONS)$(CLASS_MODIFIERS)class $CLASSNAME$EXTENDS$IMPLEMENTS$NATIVESPEC {
 
   /**
-   * 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.
    *
    * This is similar to [request] but specialized for HTTP GET requests which
    * return text content.
    *
    * See also:
    *
    * * [request]
@@ skipping 254 matching lines @@
         headers[key] = '${headers[key]}, $value';
       } else {
         headers[key] = value;
       }
     }
     return headers;
   }
 
 $!MEMBERS
 }