Update HTTP server documentation

runtime/bin/http.dart

 // Copyright (c) 2012, 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.
 
 /**
  * HTTP status codes.
  */
 interface HttpStatus {
   static final int CONTINUE = 100;
   static final int SWITCHING_PROTOCOLS = 101;
@@ skipping 42 matching lines @@
 
 
 /**
  * HTTP server.
  */
 interface HttpServer default _HttpServer {
   HttpServer();
 
   /**
    * Start listening for HTTP requests on the specified [host] and
-   * [port]. For each HTTP request the handler set through [onRequest]
-   * will be invoked. If a [port] of 0 is specified the server will
-   * choose an ephemeral port. The optional argument [backlog] can be
-   * used to specify the listen backlog for the underlying OS listen
-   * setup.
+   * [port]. If a [port] of 0 is specified the server will choose an
+   * ephemeral port. The optional argument [backlog] can be used to
+   * specify the listen backlog for the underlying OS listen
+   * setup. See [addRequestHandler] and [defaultRequestHandler] for
+   * information on how incoming HTTP requests are handled.
    */
   void listen(String host, int port, [int backlog]);
 
   /**
-   * Attach the HTTP server to an existing ServerSocket. If the HttpServer is
-   * closed, the HttpServer will just detach itself, and not close
-   * [serverSocket].
+   * Attach the HTTP server to an existing [:ServerSocket:]. If the
+   * [HttpServer] is closed, the [HttpServer] will just detach itself,
+   * and not close [serverSocket].
    */
   void listenOn(ServerSocket serverSocket);
 
   /**
    * Adds a request handler to the list of request handlers. The
    * function [matcher] is called with the request and must return
    * [:true:] if the [handler] should handle the request. The first
    * handler for which [matcher] returns [:true:] will be handed the
    * request.
    */
@@ skipping 179 matching lines @@
   /**
    * Remove all values for the specified header name. Some headers
    * have system supplied values and for these the system supplied
    * values will still be added to the collection of values for the
    * header.
    */
   void removeAll(String name);
 
   /**
    * Enumerate the headers applying the function [f] to each
-   * header. The header names passed in [name] will be all lower
+   * header. The header name passed in [name] will be all lower
    * case.
    */
   void forEach(void f(String name, List<String> values));
 
   /**
    * Gets and sets the date. The value of this property will
    * reflect the "Date" header
    */
   Date date;
 
@@ skipping 305 matching lines @@
   Socket get socket();
   List<int> get unparsedData();
 }
 
 
 class HttpException implements Exception {
   const HttpException([String this.message = ""]);
   String toString() => "HttpException: $message";
   final String message;
 }