Add documentation for HttpRequest.

sdk/lib/html/templates/html/impl/impl_XMLHttpRequest.darttemplate

Index: sdk/lib/html/templates/html/impl/impl_XMLHttpRequest.darttemplate
===================================================================
--- sdk/lib/html/templates/html/impl/impl_XMLHttpRequest.darttemplate	(revision 15846)
+++ sdk/lib/html/templates/html/impl/impl_XMLHttpRequest.darttemplate	(working copy)
@@ -4,11 +4,52 @@
 
 part of html;
 
-/// @domName $DOMNAME
+/**
+ * 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:
+ * 
+ *     var httpRequest = HttpRequest.get('http://api.dartlang.org',
+ *         (request) => print(request.responseText));
+ * 
+ * **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)
+ */
+/// @domName XMLHttpRequest
 class $CLASSNAME$EXTENDS$IMPLEMENTS$NATIVESPEC {
+  /**
+   * Creates a URL get request for the specified `url`.
+   * 
+   * After completing the request, the object will call the user-provided
+   * [onComplete] callback.
+   */
   factory $CLASSNAME.get(String url, onComplete($CLASSNAME request)) =>
       _$(CLASSNAME)FactoryProvider.create$(CLASSNAME)_get(url, onComplete);
 
+  /**
+   * Creates a URL GET request for the specified `url` with
+   * credentials such a cookie (already) set in the header or
+   * (authorization headers)[http://tools.ietf.org/html/rfc1945#section-10.2].
+   * 
+   * After completing the request, the object will call the user-provided 
+   * [onComplete] callback.
+   * 
+   * See also: (authorization headers)[http://en.wikipedia.org/wiki/Basic_access_authentication].
+   */
   factory $CLASSNAME.getWithCredentials(String url,
       onComplete($CLASSNAME request)) =>
       _$(CLASSNAME)FactoryProvider.create$(CLASSNAME)_getWithCredentials(url,