Document HttpServer.

Document HttpServer.

BUG=https://code.google.com/p/dart/issues/detail?id=11169
R=whesse@google.com

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

[Bill Hesse, 2013-06-27 10:21:03]

https://codereview.chromium.org/18049002/diff/1/sdk/lib/io/http.dart
File sdk/lib/io/http.dart (right):

https://codereview.chromium.org/18049002/diff/1/sdk/lib/io/http.dart#newcode60
sdk/lib/io/http.dart:60: * [HttpRequest] class have a [HttpResponse] associated,
through the response
Instead of ", where the ...", how about "Each [HttpRequest] has an associated
[HttpResponse] object as its .response member, and the server responds to a
request by writing to its .response member.

https://codereview.chromium.org/18049002/diff/1/sdk/lib/io/http.dart#newcode64
sdk/lib/io/http.dart:64: * ignored and no exceptions are generated for them.
Likewise, when writing to a
no exceptions or HttpRequest objects are generated for them.

https://codereview.chromium.org/18049002/diff/1/sdk/lib/io/http.dart#newcode65
sdk/lib/io/http.dart:65: * [HttpResponse], any Socket exceptions are ignore and
any future data is
[Socket] exceptions?     ignored

What does "any future data is ignored" mean?

https://codereview.chromium.org/18049002/diff/1/sdk/lib/io/http.dart#newcode68
sdk/lib/io/http.dart:68: * The [HttpRequest] implements a [Stream] and provided
the body as such. If the
The [HttpRequest] exposes the request headers, and provides the request body, if
it exists, as a stream of data.

(I would put the info about unread body in the HttpRequest class documentation).

https://codereview.chromium.org/18049002/diff/1/sdk/lib/io/http.dart#newcode77
sdk/lib/io/http.dart:77: *       // Handle requests.
Would it be misleading to just show
request.response..writeString('Hello world')
                ..close();

[Anders Johnsen, 2013-06-27 10:28:35]

PTAL

https://codereview.chromium.org/18049002/diff/1/sdk/lib/io/http.dart
File sdk/lib/io/http.dart (right):

https://codereview.chromium.org/18049002/diff/1/sdk/lib/io/http.dart#newcode60
sdk/lib/io/http.dart:60: * [HttpRequest] class have a [HttpResponse] associated,
through the response
On 2013/06/27 10:21:03, Bill Hesse wrote:
> Instead of ", where the ...", how about "Each [HttpRequest] has an associated
> [HttpResponse] object as its .response member, and the server responds to a
> request by writing to its .response member.

Done.

https://codereview.chromium.org/18049002/diff/1/sdk/lib/io/http.dart#newcode64
sdk/lib/io/http.dart:64: * ignored and no exceptions are generated for them.
Likewise, when writing to a
On 2013/06/27 10:21:03, Bill Hesse wrote:
> no exceptions or HttpRequest objects are generated for them.

Done.

https://codereview.chromium.org/18049002/diff/1/sdk/lib/io/http.dart#newcode65
sdk/lib/io/http.dart:65: * [HttpResponse], any Socket exceptions are ignore and
any future data is
On 2013/06/27 10:21:03, Bill Hesse wrote:
> [Socket] exceptions?     ignored
> 
> What does "any future data is ignored" mean?

Done.

https://codereview.chromium.org/18049002/diff/1/sdk/lib/io/http.dart#newcode68
sdk/lib/io/http.dart:68: * The [HttpRequest] implements a [Stream] and provided
the body as such. If the
On 2013/06/27 10:21:03, Bill Hesse wrote:
> The [HttpRequest] exposes the request headers, and provides the request body,
if
> it exists, as a stream of data.
> 
> (I would put the info about unread body in the HttpRequest class
documentation).

Done.

https://codereview.chromium.org/18049002/diff/1/sdk/lib/io/http.dart#newcode77
sdk/lib/io/http.dart:77: *       // Handle requests.
On 2013/06/27 10:21:03, Bill Hesse wrote:
> Would it be misleading to just show
> request.response..writeString('Hello world')
>                 ..close();
> 

I think so. I want the example to just show how to get started.

[Bill Hesse, 2013-06-27 10:38:47]

lgtm

https://codereview.chromium.org/18049002/diff/5001/sdk/lib/io/http.dart
File sdk/lib/io/http.dart (right):

https://codereview.chromium.org/18049002/diff/5001/sdk/lib/io/http.dart#newco...
sdk/lib/io/http.dart:60: * [HttpRequest] has an associated [HttpResponse] object
as its .response
(At least in monospaced type) "its .response" looks really weird.  Maybe some
other way to say it?

https://codereview.chromium.org/18049002/diff/5001/sdk/lib/io/http.dart#newco...
sdk/lib/io/http.dart:66: * Likewise, when writing to a [HttpResponse], any
[Socket] exceptions are
any [Socket] exceptions abort the response, without throwing an exception, and
any future writes to the [HttpResponse] are ignored.

[Anders Johnsen, 2013-06-27 11:35:26]

https://codereview.chromium.org/18049002/diff/5001/sdk/lib/io/http.dart
File sdk/lib/io/http.dart (right):

https://codereview.chromium.org/18049002/diff/5001/sdk/lib/io/http.dart#newco...
sdk/lib/io/http.dart:60: * [HttpRequest] has an associated [HttpResponse] object
as its .response
On 2013/06/27 10:38:47, Bill Hesse wrote:
> (At least in monospaced type) "its .response" looks really weird.  Maybe some
> other way to say it?

Done.

https://codereview.chromium.org/18049002/diff/5001/sdk/lib/io/http.dart#newco...
sdk/lib/io/http.dart:66: * Likewise, when writing to a [HttpResponse], any
[Socket] exceptions are
On 2013/06/27 10:38:47, Bill Hesse wrote:
> any [Socket] exceptions abort the response, without throwing an exception, and
> any future writes to the [HttpResponse] are ignored.

That's not really correct, as it's the socket exceptions that aborts the
connection, it's not the HttpServer's implementation that does it.

[Anders Johnsen, 2013-06-27 11:36:02]

Committed patchset #3 manually as r24513 (presubmit successful).