Edited docs for dart:io HttpRequest

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 df228f522c69b53bdb34c446c687911e1021c30b..1cf3387ed24481c0b9d2f42be3e948fa1466091c 100644
--- a/sdk/lib/io/http.dart
+++ b/sdk/lib/io/http.dart
@@ -696,77 +696,138 @@ abstract class Cookie {
 
 
 /**
- * Http request delivered to the HTTP server callback. The [HttpRequest] is a
- * [Stream] of the body content of the request. Listen to the body to handle the
+ * A server-side object
+ * that contains the content of and information about an HTTP request.
+ *
+ * __Note__: Check out the
+ * [http_server](http://pub.dartlang.org/packages/http_server)
+ * package, which makes working with the low-level
+ * dart:io HTTP server subsystem easier.
+ *
+ * HttpRequest objects are generated by an [HttpServer],
+ * which listens for HTTP requests on a specific host and port.
+ * For each request received, the HttpServer, which is a [Stream],
+ * generates an HttpRequest object and adds it to the stream.
+ *
+ * An HttpRequest object delivers the body content of the request
+ * as a stream of bytes.
+ * The object also contains information about the request,
+ * such as the method, URI, and headers.
+ *
+ * In the following code, an HttpServer listens
+ * for HTTP requests and, within the callback function,
+ * uses the HttpRequest object's `method` property to dispatch requests.
+ *
+ *     final HOST = InternetAddress.LOOPBACK_IP_V4;
+ *     final PORT = 4040;
+ *
+ *     HttpServer.bind(HOST, PORT).then((_server) {
+ *       _server.listen((HttpRequest request) {
+ *         switch (request.method) {
+ *           case 'GET': 
+ *             handleGetRequest(request);
+ *             break;
+ *           case 'POST': 
+ *             ...
+ *         }
+ *       },
+ *       onError: handleError);    // listen() failed.
+ *     }).catchError(handleError);
+ *   
+ * Listen to the HttpRequest stream to handle the
  * data and be notified once the entire body is received.
+ * An HttpRequest object contains an [HttpResponse] object,
+ * to which the server can write its response.
+ * For example, here's a skeletal callback function
+ * that responds to a request:
+ *
+ *     void handleGetRequest(HttpRequest req) {
+ *       HttpResponse res = req.response;
+ *       var body = [];
+ *       req.listen((List<int> buffer) => body.add(buffer),
+ *         onDone: () {
+ *           res.write('Received ${body.length} for request ');
+ *           res.write(' ${req.method}: ${req.uri.path}');
+ *           res.close();
+ *         },
+ *         onError: handleError);
+ *     }
  */
 abstract class HttpRequest implements Stream<List<int>> {
   /**
-   * Returns the content length of the request body. If the size of
-   * the request body is not known in advance this -1.
+   * The content length of the request body (read-only).
+   *
+   * If the size of the request body is not known in advance,
+   * this value is -1.
    */
   int get contentLength;
 
   /**
-   * Returns the method for the request.
+   * The method, such as 'GET' or 'POST', for the request (read-only).
    */
   String get method;
 
   /**
-   * Returns the URI for the request. This provides access to the
-   * path, query string and fragment identifier for the request.
+   * The URI for the request (read-only).
+   *
+   * This provides access to the
+   * path, query string, and fragment identifier for the request.
    */
   Uri get uri;
 
   /**
-   * Returns the request headers.
+   * The request headers (read-only).
    */
   HttpHeaders get headers;
 
   /**
-   * Returns the cookies in the request (from the Cookie headers).
+   * The cookies in the request, from the Cookie headers (read-only).
    */
   List<Cookie> get cookies;
 
   /**
-   * Returns the persistent connection state signaled by the client.
+   * The persistent connection state signaled by the client (read-only).
    */
   bool get persistentConnection;
 
   /**
-   * Returns the client certificate of the client making the request.
-   * Returns null if the connection is not a secure TLS or SSL connection,
+   * The client certificate of the client making the request (read-only).
+   *
+   * This value is null if the connection is not a secure TLS or SSL connection,
    * or if the server does not request a client certificate, or if the client
    * does not provide one.
    */
   X509Certificate get certificate;
 
   /**
-   * Gets the session for the given request. If the session is
-   * being initialized by this call, [:isNew:] will be true for the returned
+   * The session for the given request (read-only).
+   *
+   * If the session is
+   * being initialized by this call, [:isNew:] is true for the returned
    * session.
    * See [HttpServer.sessionTimeout] on how to change default timeout.
    */
   HttpSession get session;
 
   /**
-   * Returns the HTTP protocol version used in the request. This will
-   * be "1.0" or "1.1".
+   * The HTTP protocol version used in the request, 
+   * either "1.0" or "1.1" (read-only).
    */
   String get protocolVersion;
 
   /**
-   * Gets information about the client connection. Returns [null] if the socket
-   * is not available.
+   * Information about the client connection (read-only).
+   *
+   * Returns [null] if the socket is not available.
    */
   HttpConnectionInfo get connectionInfo;
 
   /**
-   * Gets the [HttpResponse] object, used for sending back the response to the
-   * client.
+   * The [HttpResponse] object, used for sending back the response to the
+   * client (read-only).
    *
    * If the [contentLength] of the body isn't 0, and the body isn't being read,
-   * any write calls on the [HttpResponse] will automatically drain the request
+   * any write calls on the [HttpResponse] automatically drain the request
    * body.
    */
   HttpResponse get response;