Document HttpServer.

sdk/lib/io/http.dart

Index: sdk/lib/io/http.dart
diff --git a/sdk/lib/io/http.dart b/sdk/lib/io/http.dart
index 29d561dc3101543991c2e6e1b2b18de1c5cb40db..92ea05bcb9d9cb5afe0772dbaff1b24e7fd2e4a5 100644
--- a/sdk/lib/io/http.dart
+++ b/sdk/lib/io/http.dart
@@ -55,11 +55,31 @@ abstract class HttpStatus {
 
 
 /**
- * HTTP server.
+ * The [HttpServer] class implements the server side of the HTTP
+ * protocol. The [HttpServer] is a [Stream] of [HttpRequest]s. Each
+ * [HttpRequest] has an associated [HttpResponse] object as its .response

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

(At least in monospaced type) "its .response" looks really weird.  Maybe some
other way to say it?

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

Done.

+ * member, and the server responds to a request by writing to its .response
+ * member.
+ *
+ * Incomplete requests where all or parts of the header is missing, are
+ * ignored and no exceptions or [HttpRequest] objects are generated for them.
+ * Likewise, when writing to a [HttpResponse], any [Socket] exceptions are

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

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]

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.

+ * ignored and any future writes are ignored.
+ *
+ * The [HttpRequest] exposes the request headers, and provides the request body,
+ * if it exists, as a stream of data. If the 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.
+ *     });
+ *   });
  */
 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].