Class-level docs for dart:html HttpRequest.

Class-level docs for dart:html HttpRequest.

BUG=
R=sethladd@google.com

Committed: https://code.google.com/p/dart/source/detail?r=27133

[mem, 2013-09-03 20:28:29]

Thanks in advance for your insightful feedback.

mem

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

https://codereview.chromium.org/23556009/diff/1/sdk/lib/html/dart2js/html_dar...
File sdk/lib/html/dart2js/html_dart2js.dart (right):

https://codereview.chromium.org/23556009/diff/1/sdk/lib/html/dart2js/html_dar...
sdk/lib/html/dart2js/html_dart2js.dart:12867: + * A client-side request for
getting data from a URL.
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"

https://codereview.chromium.org/23556009/diff/1/sdk/lib/html/dart2js/html_dar...
sdk/lib/html/dart2js/html_dart2js.dart:12869: + * HttpRequest can be used to
obtain data from http, ftp, and file protocols.
HTTP and FTP

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

https://codereview.chromium.org/23556009/diff/1/sdk/lib/html/dart2js/html_dar...
sdk/lib/html/dart2js/html_dart2js.dart:12871: + * The simplest way to get the
contents of a plain text file, such as a
drop "plain", as most people wouldn't say that json is a plain text file.

https://codereview.chromium.org/23556009/diff/1/sdk/lib/html/dart2js/html_dar...
sdk/lib/html/dart2js/html_dart2js.dart:12878: + *       .then( ... )
please make this valid syntax

https://codereview.chromium.org/23556009/diff/1/sdk/lib/html/dart2js/html_dar...
sdk/lib/html/dart2js/html_dart2js.dart:12880: + *     }
typo, no closing } here

https://codereview.chromium.org/23556009/diff/1/sdk/lib/html/dart2js/html_dar...
sdk/lib/html/dart2js/html_dart2js.dart:12883: + * **Important**:
How about a header here? maybe ## ?

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

https://codereview.chromium.org/23556009/diff/1/sdk/lib/html/dart2js/html_dar...
sdk/lib/html/dart2js/html_dart2js.dart:12912: +   * Creates a URL GET request
for the specified [url].
drop URL here, I don't think we need it

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

Hey Seth:
Thanks for the feedback. Please check the AJAX wording....

mem

https://codereview.chromium.org/23556009/diff/1/sdk/lib/html/dart2js/html_dar...
File sdk/lib/html/dart2js/html_dart2js.dart (right):

https://codereview.chromium.org/23556009/diff/1/sdk/lib/html/dart2js/html_dar...
sdk/lib/html/dart2js/html_dart2js.dart:12867: + * A client-side request for
getting data from a URL.
On 2013/09/03 21:49:25, sethladd wrote:
> 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"

Done.

https://codereview.chromium.org/23556009/diff/1/sdk/lib/html/dart2js/html_dar...
sdk/lib/html/dart2js/html_dart2js.dart:12869: + * HttpRequest can be used to
obtain data from http, ftp, and file protocols.
On 2013/09/03 21:49:25, sethladd wrote:
> HTTP and FTP
> 
> drop the file part... not sure that works unless you start chrome in a special
> way.

Done.

https://codereview.chromium.org/23556009/diff/1/sdk/lib/html/dart2js/html_dar...
sdk/lib/html/dart2js/html_dart2js.dart:12871: + * The simplest way to get the
contents of a plain text file, such as a
On 2013/09/03 21:49:25, sethladd wrote:
> drop "plain", as most people wouldn't say that json is a plain text file.

Done.

https://codereview.chromium.org/23556009/diff/1/sdk/lib/html/dart2js/html_dar...
sdk/lib/html/dart2js/html_dart2js.dart:12878: + *       .then( ... )
On 2013/09/03 21:49:25, sethladd wrote:
> please make this valid syntax

Done.

https://codereview.chromium.org/23556009/diff/1/sdk/lib/html/dart2js/html_dar...
sdk/lib/html/dart2js/html_dart2js.dart:12880: + *     }
On 2013/09/03 21:49:25, sethladd wrote:
> typo, no closing } here

Done.

https://codereview.chromium.org/23556009/diff/1/sdk/lib/html/dart2js/html_dar...
sdk/lib/html/dart2js/html_dart2js.dart:12883: + * **Important**:
On 2013/09/03 21:49:25, sethladd wrote:
> How about a header here? maybe ## ?
> 
> Also, instead of Important, how about a more useful header like "fetching data
> from other servers" ?

Done.

https://codereview.chromium.org/23556009/diff/1/sdk/lib/html/dart2js/html_dar...
sdk/lib/html/dart2js/html_dart2js.dart:12912: +   * Creates a URL GET request
for the specified [url].
On 2013/09/03 21:49:25, sethladd wrote:
> drop URL here, I don't think we need it

Done.

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

https://codereview.chromium.org/23556009/diff/1/sdk/lib/html/dart2js/html_dar...
File sdk/lib/html/dart2js/html_dart2js.dart (right):

https://codereview.chromium.org/23556009/diff/1/sdk/lib/html/dart2js/html_dar...
sdk/lib/html/dart2js/html_dart2js.dart:12867: + * A client-side request for
getting data from a URL.
Also use XHR. I was always told that XHR was a more literate term than AJAX.

https://codereview.chromium.org/23556009/diff/1/sdk/lib/html/dart2js/html_dar...
sdk/lib/html/dart2js/html_dart2js.dart:12876: + *     var path = 'myData.json';
This example doesn't show anything being done with the data. Make the example
real.

https://codereview.chromium.org/23556009/diff/1/sdk/lib/html/dart2js/html_dar...
sdk/lib/html/dart2js/html_dart2js.dart:12877: + *    
HttpRequest.getString(path)
Incorrect indentation. The .then() and .catchError() should have 4-space
indents.

https://codereview.chromium.org/23556009/diff/1/sdk/lib/html/dart2js/html_dar...
sdk/lib/html/dart2js/html_dart2js.dart:12884: + * For security reasons, browsers
impose restrictions on requests
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]

et voila.

https://codereview.chromium.org/23556009/diff/1/sdk/lib/html/dart2js/html_dar...
File sdk/lib/html/dart2js/html_dart2js.dart (right):

https://codereview.chromium.org/23556009/diff/1/sdk/lib/html/dart2js/html_dar...
sdk/lib/html/dart2js/html_dart2js.dart:12867: + * A client-side request for
getting data from a URL.
On 2013/09/03 23:00:57, shailentuli wrote:
> Also use XHR. I was always told that XHR was a more literate term than AJAX. 

Done.

https://codereview.chromium.org/23556009/diff/1/sdk/lib/html/dart2js/html_dar...
sdk/lib/html/dart2js/html_dart2js.dart:12876: + *     var path = 'myData.json';
On 2013/09/03 23:00:57, shailentuli wrote:
> This example doesn't show anything being done with the data. Make the example
> real.

Done.

https://codereview.chromium.org/23556009/diff/1/sdk/lib/html/dart2js/html_dar...
sdk/lib/html/dart2js/html_dart2js.dart:12877: + *    
HttpRequest.getString(path)
On 2013/09/03 23:00:57, shailentuli wrote:
> Incorrect indentation. The .then() and .catchError() should have 4-space
> indents. 

Done.

https://codereview.chromium.org/23556009/diff/1/sdk/lib/html/dart2js/html_dar...
sdk/lib/html/dart2js/html_dart2js.dart:12884: + * For security reasons, browsers
impose restrictions on requests
On 2013/09/03 23:00:57, shailentuli wrote:
> Maybe I don't understand something about DartDoc formatting, but why do some
> sentences have so few words?  This is hard to read. 

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

[sethladd, 2013-09-04 01:08:32]

lgtm

[mem, 2013-09-04 15:47:44]

Committed patchset #4 manually as r27133 (presubmit successful).