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..91b4eb27c0c266797cfc587e907098108e1c0b78 100644
--- a/sdk/lib/io/http.dart
+++ b/sdk/lib/io/http.dart
@@ -696,25 +696,71 @@ 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.
+ * 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, such as the method, URI,
+ * and headers, about the request.

[Kathy Walrath, 2013/08/27 07:18:29]

I'd move "about the request" up after information, to reduce the amount of
commas/interruption.

[mem, 2013/08/27 08:13:53]

Done.

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

[Kathy Walrath, 2013/08/27 07:18:29]

should that be [method]?

[mem, 2013/08/27 08:13:53]

Done.

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

[Kathy Walrath, 2013/08/27 07:18:29]

The "." notation seems weird to me here. How about:

.listen -> listen or listen()

[mem, 2013/08/27 08:13:53]

Done.

+ *     }, onError: printError); // .then failed.

[Kathy Walrath, 2013/08/27 07:18:29]

.then -> then or then()

[mem, 2013/08/27 08:13:53]

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:

[Kathy Walrath, 2013/08/27 07:18:29]

It'd be nice to see handleRequest specified somewhere (either in this snippet or
the one above), so they can make the connection between specifying the callback
and implementing it.

[mem, 2013/08/27 08:13:53]

Done.

+ *
+ *     void handleRequest(HttpRequest req) {
+ *       HttpResponse res = req.response; // Send the response via this object.
+ *       print('${req.method}: ${req.uri.path}'); // Print the method and URI.
+ * 
+ *       req.listen((List<int> buffer) { // Listen for the request content.
+ *         // buffer contains the content of the request.
+ *         ...
+ *         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.
+   * Returns the content length of the request body.
+   *
+   * If the size of the request body is not known in advance,
+   * this returns -1.

[Kathy Walrath, 2013/08/27 07:18:29]

We usually use noun phrases for properties, even for getters. Maybe:

The content length... (read-only).
OR
The content length.... [read only]

this returns -> this value is

[mem, 2013/08/27 08:13:53]

Done.

    */
   int get contentLength;
 
   /**
-   * Returns the method for the request.
+   * Returns the method, such as 'GET' or 'POST', for the request.

[Kathy Walrath, 2013/08/27 07:18:29]

The method, ... request (read-only).

(or follow whatever convention we agree on)

[mem, 2013/08/27 08:13:53]

Done.

    */
   String get method;
 
   /**
-   * Returns the URI for the request. This provides access to the
-   * path, query string and fragment identifier for the request.
+   * Returns the URI for the request.

[Kathy Walrath, 2013/08/27 07:18:29]

The URI... (read-only).

[mem, 2013/08/27 08:13:53]

Done.

+   *
+   * This provides access to the
+   * path, query string, and fragment identifier for the request.
    */
   Uri get uri;
 
@@ -735,6 +781,7 @@ abstract class HttpRequest implements Stream<List<int>> {
 
   /**
    * Returns the client certificate of the client making the request.

[Kathy Walrath, 2013/08/27 07:18:29]

nounify, read-only

[mem, 2013/08/27 08:13:53]

Done.

+   *
    * Returns 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.
@@ -742,7 +789,9 @@ abstract class HttpRequest implements Stream<List<int>> {
   X509Certificate get certificate;
 
   /**
-   * Gets the session for the given request. If the session is
+   * Gets the session for the given request.

[Kathy Walrath, 2013/08/27 07:18:29]

nounify, read-only

[mem, 2013/08/27 08:13:53]

Done.

+   *
+   * If the session is
    * being initialized by this call, [:isNew:] will be true for the returned
    * session.
    * See [HttpServer.sessionTimeout] on how to change default timeout.
@@ -750,14 +799,15 @@ abstract class HttpRequest implements Stream<List<int>> {
   HttpSession get session;
 
   /**
-   * Returns the HTTP protocol version used in the request. This will
-   * be "1.0" or "1.1".
+   * Returns the HTTP protocol version used in the request, 

[Kathy Walrath, 2013/08/27 07:18:29]

nounify

[mem, 2013/08/27 08:13:53]

Done.

+   * either "1.0" or "1.1".
    */
   String get protocolVersion;
 
   /**
-   * Gets information about the client connection. Returns [null] if the socket
-   * is not available.
+   * Gets information about the client connection.

[Kathy Walrath, 2013/08/27 07:18:29]

nounify, read-only

[mem, 2013/08/27 08:13:53]

Done.

+   *
+   * Returns [null] if the socket is not available.
    */
   HttpConnectionInfo get connectionInfo;