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..5e67e0bfef3373d7e969c18f639826f43acfc1a2 100644
--- a/sdk/lib/io/http.dart
+++ b/sdk/lib/io/http.dart
@@ -696,77 +696,128 @@ 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.
+ *
+ * An [HttpServer] listens for HTTP requests on a specific host and port.

[Søren Gjesse, 2013/08/27 09:11:10]

This section mentions a callback function. I think it is better to just say that
there is a stream of HttpRequests, maybe start with something like this:

An [HttpServer] generates a [Stream] of HttpRequest objects. For each HTTP
request which comes in a HttpRequest is added to the stream. The HttpRequest
object...

[mem, 2013/08/27 12:31:56]

Done.

+ * When a request comes in, the server's callback function receives
+ * an HttpRequest object—a [Stream] that delivers the body content
+ * of the request.
+ * The object also contains information about the request,
+ * such as the method, URI, and headers, about the request.

[Kathy Walrath, 2013/08/27 08:23:11]

strike ", about the request"

[mem, 2013/08/27 12:31:56]

Done.

+ * The following code listens
+ * for HTTP requests and, within the callback function,
+ * uses the HttpRequest object's [method] property to triage requests.

[Søren Gjesse, 2013/08/27 09:11:10]

Maybe change triage to dispatch.

[mem, 2013/08/27 12:31:56]

Done.

+ *
+ *     final HOST = '127.0.0.1'; // localhost.

[Søren Gjesse, 2013/08/27 09:11:10]

Use InternetAddress.LOOPBACK_IP_V4 instead of '127.0.0.1'.

[mem, 2013/08/27 12:31:56]

Done.

+ *     final PORT = 4040;
+ *
+ *     HttpServer.bind(HOST, PORT).then((_server) {
+ *       _server.listen((HttpRequest request) {
+ *         switch (request.method) {
+ *           case 'GET': 
+ *             handleGetRequest(request);
+ *             break;
+ *           case 'POST': 
+ *             ...
+ *         }
+ *       },
+ *       onError: printError);  // listen() failed.
+ *     }, onError: printError); // then() failed.

[Søren Gjesse, 2013/08/27 09:11:10]

Future.then does not have an optional named onError argument, but an optional
positional argument for the onError.

However we encurage users to use catchError instead (the doc for Future.then
says: "In most cases, it is more readable to use catchError separately, possibly
with a test parameter, instead of handling both value and error in a single then
call")

So this line should be:

}).catchError(printError);

[mem, 2013/08/27 12:31:56]

Done.

+ *
+ * Listen to the HttpRequest to handle the
  * data and be notified once the entire body is received.
+ * The HttpRequest object contains an [HttpResponse] object,
+ * to which the server can write its response.
+ * For example, here's a skeletal callback function for a request:
+ *
+ *     void handleGetRequest(HttpRequest req) {
+ *       HttpResponse res = req.response; // Send the response via this object.
+ *       print('${req.method}: ${req.uri.path}'); // Print the method and URI.

[Søren Gjesse, 2013/08/27 09:11:10]

I don't think we should use pint in the examples. How about sending whi in the
response - see comment below.

[mem, 2013/08/27 12:31:56]

Done.

+ * 
+ *       req.listen((List<int> buffer) { // Listen for the request content.
+ *         // buffer contains the content of the request.

[Søren Gjesse, 2013/08/27 09:11:10]

As this is a stream the buffer might not contain all the request content. This
should look something like this instead:

// Request data is a stream of bytes.
req.fold([], (list, data) => list..add(data))
   .then((body) {
     res.write('Received ${body.length} for request ${req.method}:
${req.uri.path}');
     res.close();
    }).catchError(printError);

or if we want to use listen explicitly:

var body = [];
req.listen((List<int> buffer) => body.add(buffer),
           onDone: () {
             res.write('Received ${body.length} for request ${req.method}:
${req.uri.path}');
             res.close();
           },
           onError(printError));

I have not tried to run this code :-)

[mem, 2013/08/27 12:31:56]

Done.

+ *         ...
+ *         res.write( ... );
+ *       },
+ *       onError: printError);
+ *     }
  */
 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), also read-only.

[Søren Gjesse, 2013/08/27 09:11:10]

also read-only -> (read only)

for consistency.

[mem, 2013/08/27 12:31:56]

Done.

    */
   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;