Add documentation for HttpRequest.

Add documentation for HttpRequest.
Committed: https://code.google.com/p/dart/source/detail?r=15848

[Emily Fortuna, 2012-12-06 19:11:05]

the "docs editable" tag was not being generated for constructors, so I added it.
There's some other spots we're missing documentation that I wrote, but this gets
most of it in, for starters.

[Kathy Walrath, 2012-12-06 19:40:29]

Yay, more docs! I started taking a look at the words.

Here's what I have, so far. Some of the comments apply globally, so I thought
it'd be better to get you a little bit soon than to spend a lot of time on this
(and possibly duplicate Andrei's review).

Question: I seem to always put comments in the first file, even though the
specific file is probably more appropriate. Is that OK?

-k-

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

https://codereview.chromium.org/11471005/diff/1/sdk/lib/html/dart2js/html_dar...
sdk/lib/html/dart2js/html_dart2js.dart:5611: /// Returns the [Window] associated
with the document.
No need to link to [Window], since that's in the signature. Also, we should come
up with a convention for read-only fields; it seems weird to use verbs for
getters/setters. Maybe:

 * The window associated with this document;
 * this is a read-only property.

https://codereview.chromium.org/11471005/diff/1/sdk/lib/html/dart2js/html_dar...
sdk/lib/html/dart2js/html_dart2js.dart:9686: /// HttpRequest is a utility for
retrieving data from a URL.
Does this generate OK? /// has been eating line endings for me.

Change this description to be a noun phrase, instead of a sentence. Maybe:

A utility for retrieving data from a URL.

https://codereview.chromium.org/11471005/diff/1/sdk/lib/html/dart2js/html_dar...
sdk/lib/html/dart2js/html_dart2js.dart:9688: /// HttpRequest can be used to
obtain data from http, ftp, as well as file
as well as -> and

https://codereview.chromium.org/11471005/diff/1/sdk/lib/html/dart2js/html_dar...
sdk/lib/html/dart2js/html_dart2js.dart:9691: /// For example, suppose we're
developing this Dart documentation page, and we
this Dart documentation page
->
(something more general and short; I got confused about what "this" means)

https://codereview.chromium.org/11471005/diff/1/sdk/lib/html/dart2js/html_dar...
sdk/lib/html/dart2js/html_dart2js.dart:9692: /// wish to retrieve the html of
the top level page and print it out.
html -> HTML
top level -> top-level

https://codereview.chromium.org/11471005/diff/1/sdk/lib/html/dart2js/html_dar...
sdk/lib/html/dart2js/html_dart2js.dart:9695: ///     var httpRequest =
HttpRequest.get('http://api.dartlang.org', (request) =>
print(request.responseText));
split into 2 lines?

https://codereview.chromium.org/11471005/diff/1/sdk/lib/html/dart2js/html_dar...
sdk/lib/html/dart2js/html_dart2js.dart:9699: /// port, and application layer
protocol) as the url you are trying to access
url -> URL

https://codereview.chromium.org/11471005/diff/1/sdk/lib/html/dart2js/html_dar...
sdk/lib/html/dart2js/html_dart2js.dart:9704: /// [Dart article on using
HttpRequests](http://www.dartlang.org/articles/json-web-service/#getting-data),
It'd be nice to make this a bulleted list by inserting a line before this,
adding "* " to each line, and removing the "," and "and".

(e.g. see the DivElement class description)

Alternatively, convert this to a real sentence. E.g.: Also see the [Dart
article...

https://codereview.chromium.org/11471005/diff/1/sdk/lib/html/dart2js/html_dar...
sdk/lib/html/dart2js/html_dart2js.dart:9709: /// Construct a URL get request at
the specified [url]. After
Construct -> Creates

at -> for?

Put the first sentence on its own line.

[Emily Fortuna, 2012-12-06 21:08:47]

PTAL

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

https://codereview.chromium.org/11471005/diff/1/sdk/lib/html/dart2js/html_dar...
sdk/lib/html/dart2js/html_dart2js.dart:5611: /// Returns the [Window] associated
with the document.
On 2012/12/06 19:40:29, Kathy Walrath wrote:
> No need to link to [Window], since that's in the signature. Also, we should
come
> up with a convention for read-only fields; it seems weird to use verbs for
> getters/setters. Maybe:
> 
>  * The window associated with this document;
>  * this is a read-only property.

This actually wasn't one of my changes. It was added in from the json file. Make
the change anyway?

https://codereview.chromium.org/11471005/diff/1/sdk/lib/html/dart2js/html_dar...
sdk/lib/html/dart2js/html_dart2js.dart:9686: /// HttpRequest is a utility for
retrieving data from a URL.
On 2012/12/06 19:40:29, Kathy Walrath wrote:
> Does this generate OK? /// has been eating line endings for me.
> 
> Change this description to be a noun phrase, instead of a sentence. Maybe:
> 
> A utility for retrieving data from a URL.

Done.

https://codereview.chromium.org/11471005/diff/1/sdk/lib/html/dart2js/html_dar...
sdk/lib/html/dart2js/html_dart2js.dart:9688: /// HttpRequest can be used to
obtain data from http, ftp, as well as file
On 2012/12/06 19:40:29, Kathy Walrath wrote:
> as well as -> and

Done.

https://codereview.chromium.org/11471005/diff/1/sdk/lib/html/dart2js/html_dar...
sdk/lib/html/dart2js/html_dart2js.dart:9692: /// wish to retrieve the html of
the top level page and print it out.
On 2012/12/06 19:40:29, Kathy Walrath wrote:
> html -> HTML
> top level -> top-level

Done.

https://codereview.chromium.org/11471005/diff/1/sdk/lib/html/dart2js/html_dar...
sdk/lib/html/dart2js/html_dart2js.dart:9695: ///     var httpRequest =
HttpRequest.get('http://api.dartlang.org', (request) =>
print(request.responseText));
On 2012/12/06 19:40:29, Kathy Walrath wrote:
> split into 2 lines?

Done.

https://codereview.chromium.org/11471005/diff/1/sdk/lib/html/dart2js/html_dar...
sdk/lib/html/dart2js/html_dart2js.dart:9699: /// port, and application layer
protocol) as the url you are trying to access
On 2012/12/06 19:40:29, Kathy Walrath wrote:
> url -> URL

Done.

https://codereview.chromium.org/11471005/diff/1/sdk/lib/html/dart2js/html_dar...
sdk/lib/html/dart2js/html_dart2js.dart:9704: /// [Dart article on using
HttpRequests](http://www.dartlang.org/articles/json-web-service/#getting-data),
On 2012/12/06 19:40:29, Kathy Walrath wrote:
> It'd be nice to make this a bulleted list by inserting a line before this,
> adding "* " to each line, and removing the "," and "and".
> 
> (e.g. see the DivElement class description)
> 
> Alternatively, convert this to a real sentence. E.g.: Also see the [Dart
> article...

Done.

https://codereview.chromium.org/11471005/diff/1/sdk/lib/html/dart2js/html_dar...
sdk/lib/html/dart2js/html_dart2js.dart:9709: /// Construct a URL get request at
the specified [url]. After
On 2012/12/06 19:40:29, Kathy Walrath wrote:
> Construct -> Creates
> 
> at -> for?
> 
> Put the first sentence on its own line.

Done.

[Kathy Walrath, 2012-12-06 22:53:14]

A few picky comments, plus a couple that actually matter, format-wise (in the
bulleted list way down at the bottom).  I tested in Dart Editor to make sure I
was telling the truth about the bulleted list formatting.

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

https://codereview.chromium.org/11471005/diff/1/sdk/lib/html/dart2js/html_dar...
sdk/lib/html/dart2js/html_dart2js.dart:5611: /// Returns the [Window] associated
with the document.
> This actually wasn't one of my changes. It was added in from the json file.
Make
> the change anyway?

No, let's keep this small. I'll make a note for later...

https://codereview.chromium.org/11471005/diff/6002/sdk/lib/html/templates/htm...
File sdk/lib/html/templates/html/impl/impl_XMLHttpRequest.darttemplate (right):

https://codereview.chromium.org/11471005/diff/6002/sdk/lib/html/templates/htm...
sdk/lib/html/templates/html/impl/impl_XMLHttpRequest.darttemplate:8: *
HttpRequest is a utility for retrieving data from a URL.
HttpRequest is a -> A

https://codereview.chromium.org/11471005/diff/6002/sdk/lib/html/templates/htm...
sdk/lib/html/templates/html/impl/impl_XMLHttpRequest.darttemplate:13: * For
example, suppose we're developing these API-docs, and we
API-docs -> API docs

https://codereview.chromium.org/11471005/diff/6002/sdk/lib/html/templates/htm...
sdk/lib/html/templates/html/impl/impl_XMLHttpRequest.darttemplate:14: * wish to
retrieve the html of the top level page and print it out.
html -> HTML
top level -> top-level

https://codereview.chromium.org/11471005/diff/6002/sdk/lib/html/templates/htm...
sdk/lib/html/templates/html/impl/impl_XMLHttpRequest.darttemplate:20: * It is
important to note that with the default behavior of this class, your
It is important to note that with
->
**Important:** With

https://codereview.chromium.org/11471005/diff/6002/sdk/lib/html/templates/htm...
sdk/lib/html/templates/html/impl/impl_XMLHttpRequest.darttemplate:26: * See
also:
We need a blank space beneath this line for the list to be processed properly.

https://codereview.chromium.org/11471005/diff/6002/sdk/lib/html/templates/htm...
sdk/lib/html/templates/html/impl/impl_XMLHttpRequest.darttemplate:27: *     *
[Dart article on using
HttpRequests](http://www.dartlang.org/articles/json-web-service/#getting-data)
Remove the excess spaces before the * so it won't be interpreted as code:

 * * [Dart article...

[Emily Fortuna, 2012-12-06 23:04:07]

PTAL. 
Sorry about that -- some of my fixes got clobbered. :-(

[Kathy Walrath, 2012-12-07 00:46:29]

lgtm

A couple of tweaks, if you can, but not a big deal.

https://codereview.chromium.org/11471005/diff/14010/sdk/lib/html/templates/ht...
File sdk/lib/html/templates/html/impl/impl_XMLHttpRequest.darttemplate (right):

https://codereview.chromium.org/11471005/diff/14010/sdk/lib/html/templates/ht...
sdk/lib/html/templates/html/impl/impl_XMLHttpRequest.darttemplate:37: * After
completing the request, the object will call the user provided

user provided -> user-provided
(since it's before the noun)

https://codereview.chromium.org/11471005/diff/14010/sdk/lib/html/templates/ht...
sdk/lib/html/templates/html/impl/impl_XMLHttpRequest.darttemplate:48: * After
completing the request, the object will call the user provided
user provided -> user-provided

[Andrei Mouravski, 2012-12-07 17:13:37]

With 3 minutes to go!

https://codereview.chromium.org/11471005/diff/3004/sdk/lib/html/dart2js/html_...
File sdk/lib/html/dart2js/html_dart2js.dart (right):

https://codereview.chromium.org/11471005/diff/3004/sdk/lib/html/dart2js/html_...
sdk/lib/html/dart2js/html_dart2js.dart:9714: * Creates a URL get request for the
specified [url].
No [] in first sentences, here and below.

https://codereview.chromium.org/11471005/diff/3004/sdk/lib/html/dart2js/html_...
sdk/lib/html/dart2js/html_dart2js.dart:9730: * See also (authorization
headers)[http://en.wikipedia.org/wiki/Basic_access_authentication].
Colon after See also

https://codereview.chromium.org/11471005/diff/3004/sdk/lib/html/dart2js/html_...
sdk/lib/html/dart2js/html_dart2js.dart:9739: * General constructor for any type
of request (GET, POST, etc). To be used
Put the second sentence to its own paragraph.

Maybe:
"The constructed request is used with [open] to do blah blah blah..."

https://codereview.chromium.org/11471005/diff/3004/sdk/lib/html/dart2js/html_...
sdk/lib/html/dart2js/html_dart2js.dart:9754: * Get the set of
[HttpRequestEvents] that this request can respond to.
"Get the request events that this request can respond to."

Make second bit a new paragraph.

https://codereview.chromium.org/11471005/diff/3004/sdk/lib/html/dart2js/html_...
sdk/lib/html/dart2js/html_dart2js.dart:9833: * or authorization headers; false
otherwise. This value is ignored for
Second sentences should go in a new paragraph. Here and below.

https://codereview.chromium.org/11471005/diff/3004/sdk/lib/html/dart2js/html_...
sdk/lib/html/dart2js/html_dart2js.dart:9905: * Send the request with any given
`data`. See also
See also in new paragraph with a colon after it.

https://codereview.chromium.org/11471005/diff/3004/sdk/lib/html/dart2js/html_...
sdk/lib/html/dart2js/html_dart2js.dart:9906: * [MDN send()
docs](https://developer.mozilla.org/en-US/docs/DOM/XMLHttpRequest#send()).
I think the patter we have been using is:
"See also:
  * [Blah blah docs](link) from Source.