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 b5106a99e32bc233589206517bf26b14c2619dd6..3b5ff921619a71001ba0e1c0227f30d00008e7a8 100644
--- a/sdk/lib/html/dart2js/html_dart2js.dart
+++ b/sdk/lib/html/dart2js/html_dart2js.dart
@@ -12864,27 +12864,43 @@ class HtmlOptionsCollection extends HtmlCollection native "HTMLOptionsCollection
 
 
 /**
- * A utility for retrieving data from a URL.
+ * A client-side request for getting data from a URL.

[sethladd, 2013/09/03 21:49:25]

somewhere, use the word AJAX because some people will be searchign for it.

Also, use XMLHttpRequest somewhere, which is the old name for this. Developers
will search with that term. Maybe: "formally known as XMLHttpRequest"

[mem, 2013/09/03 22:49:13]

Done.

[shailentuli, 2013/09/03 23:00:57]

Also use XHR. I was always told that XHR was a more literate term than AJAX. 

[mem, 2013/09/03 23:37:40]

Done.

  *
- * HttpRequest can be used to obtain data from http, ftp, and file
- * protocols.
+ * HttpRequest can be used to obtain data from http, ftp, and file protocols.

[sethladd, 2013/09/03 21:49:25]

HTTP and FTP

drop the file part... not sure that works unless you start chrome in a special
way.

[mem, 2013/09/03 22:49:13]

Done.

  *
- * 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:
+ * The simplest way to get the contents of a plain text file, such as a

[sethladd, 2013/09/03 21:49:25]

drop "plain", as most people wouldn't say that json is a plain text file.

[mem, 2013/09/03 22:49:13]

Done.

+ * JSON-formatted file, is with [getString].
+ * For example, to get the contents of a file named 'myData.json',
+ * you could use this code:
  *
- *     HttpRequest.getString('http://api.dartlang.org').then((response) {
- *       print(response);
- *     });
+ *     var path = 'myData.json';

[shailentuli, 2013/09/03 23:00:57]

This example doesn't show anything being done with the data. Make the example
real.

[mem, 2013/09/03 23:37:40]

Done.

+ *     HttpRequest.getString(path)

[shailentuli, 2013/09/03 23:00:57]

Incorrect indentation. The .then() and .catchError() should have 4-space
indents. 

[mem, 2013/09/03 23:37:40]

Done.

+ *       .then( ... )

[sethladd, 2013/09/03 21:49:25]

please make this valid syntax

[mem, 2013/09/03 22:49:13]

Done.

+ *       .catchError( ... );
+ *     }

[sethladd, 2013/09/03 21:49:25]

typo, no closing } here

[mem, 2013/09/03 22:49:13]

Done.

  *
- * **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:
+ * **Important**:

[sethladd, 2013/09/03 21:49:25]

How about a header here? maybe ## ?

Also, instead of Important, how about a more useful header like "fetching data
from other servers" ?

[mem, 2013/09/03 22:49:13]

Done.

+ * For security reasons, browsers impose restrictions on requests

[shailentuli, 2013/09/03 23:00:57]

Maybe I don't understand something about DartDoc formatting, but why do some
sentences have so few words?  This is hard to read. 

[mem, 2013/09/03 23:37:40]

I break the lines based on phrasing because it's easier to edit and do diffs.

+ * 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 documentation
  *
+ * * [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)
@@ -12893,7 +12909,7 @@ class HtmlOptionsCollection extends HtmlCollection native "HTMLOptionsCollection
 class HttpRequest extends XmlHttpRequestEventTarget native "XMLHttpRequest" {
 
   /**
-   * Creates a URL get request for the specified [url].
+   * Creates a URL GET request for the specified [url].

[sethladd, 2013/09/03 21:49:25]

drop URL here, I don't think we need it

[mem, 2013/09/03 22:49:13]

Done.

    *
    * The server response must be a `text/` mime type for this request to
    * succeed.