Document HttpServer.

sdk/lib/io/http.dart

 // Copyright (c) 2013, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 part of dart.io;
 
 /**
  * HTTP status codes.
  */
 abstract class HttpStatus {
@@ skipping 37 matching lines @@
   static const int BAD_GATEWAY = 502;
   static const int SERVICE_UNAVAILABLE = 503;
   static const int GATEWAY_TIMEOUT = 504;
   static const int HTTP_VERSION_NOT_SUPPORTED = 505;
   // Client generated status code.
   static const int NETWORK_CONNECT_TIMEOUT_ERROR = 599;
 }
 
 
 /**
- * HTTP server.
+ * The [HttpServer] class implements the server side of the HTTP
+ * protocol. The [HttpServer] is a [Stream] of [HttpRequest]s, where the
+ * [HttpRequest] class have a [HttpResponse] associated, through the response

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

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.

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

Done.

+ * field.
+ *
+ * Incomplete requests where all or parts of the header is missing, are
+ * ignored and no exceptions are generated for them. Likewise, when writing to a

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

no exceptions or HttpRequest objects are generated for them.

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

Done.

+ * [HttpResponse], any Socket exceptions are ignore and any future data is

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

[Socket] exceptions?     ignored

What does "any future data is ignored" mean?

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

Done.

+ * ignored.
+ *
+ * The [HttpRequest] implements a [Stream] and provided the body as such. If the

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

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).

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

Done.

+ * body is unread, it'll be drained when the [HttpResponse] is being written
+ * to or closed.
+ *
+ * The following example shows how to bind a [HttpServer] to a IPv6
+ * [InternetAddress] on port 80, and listening to requests.
+ *
+ *   HttpServer.bind(InternetAddress.ANY_IP_V6, 80).then((server) {
+ *     server.listen((HttpRequest request) {
+ *       // Handle requests.

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

Would it be misleading to just show
request.response..writeString('Hello world')
                ..close();

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

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

+ *     });
+ *   });
  */
 abstract class HttpServer implements Stream<HttpRequest> {
-  // TODO(ajohnsen): Document with example, once the stream API is final.
-  // TODO(ajohnsen): Add HttpServer.secure.
   /**
    * Starts listening for HTTP requests on the specified [address] and
    * [port].
    *
    * The [address] can either be a [String] or an
    * [InternetAddress]. If [address] is a [String], [bind] will
    * perform a [InternetAddress.lookup] and use the first value in the
    * list. To listen on the loopback adapter, which will allow only
    * incoming connections from the local host, use the value
    * [InternetAddress.LOOPBACK_IP_V4] or
@@ skipping 1315 matching lines @@
 
 class RedirectException implements HttpException {
   final String message;
   final List<RedirectInfo> redirects;
 
   const RedirectException(String this.message,
                           List<RedirectInfo> this.redirects);
 
   String toString() => "RedirectException: $message";
 }