Edited docs for dart:io HttpRequest

sdk/lib/io/http.dart

 // Copyright (c) 2013, 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.
 
 part of dart.io;
 
 /**
  * HTTP status codes.
  */
 abstract class HttpStatus {
@@ skipping 678 matching lines @@
   /**
    * Returns the formatted string representation of the cookie. The
    * string representation can be used for for setting the Cookie or
    * 'set-cookie' headers
    */
   String toString();
 }
 
 
 /**
- * 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;
 
   /**
    * Returns the request headers.

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

nounify, add "read only"

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

Done.

    */
   HttpHeaders get headers;
 
   /**
    * Returns the cookies in the request (from the Cookie headers).

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

nounify, add "read only"

Actually, I wonder if "read only" is needed here, since the "from" is a strong
hint about that. We should decide on the rules.

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

Done.

    */
   List<Cookie> get cookies;
 
   /**
    * Returns the persistent connection state signaled by the client.

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

nounify

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

Done.

    */
   bool get persistentConnection;
 
   /**
    * 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.
    */
   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.
    */
   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;
 
   /**
    * Gets the [HttpResponse] object, used for sending back the response to the
    * client.
    *
    * 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
    * body.
    */
   HttpResponse get response;

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

nounify, read-only

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

Done.

 }
 
 
 /**
  * An [HttpResponse] represents the headers and data to be returned to
  * a client in response to an HTTP request.
  *
  * This object has a number of properties for setting up the HTTP
  * header of the response. When the header has been set up the methods
  * from the [IOSink] can be used to write the actual body of the HTTP
@@ skipping 739 matching lines @@
   final String message;
   final List<RedirectInfo> redirects;
 
   const RedirectException(String this.message,
                           List<RedirectInfo> this.redirects);
 
   String toString() => "RedirectException: $message";
 
   Uri get uri => redirects.last.location;
 }